Everything under https://api.timetracker.live/api/v1/ is a contract. Once
somebody depends on it, changing what it returns or accepts is a new version
rather than an edit. The endpoints our own apps call are a different, private
thing under /api/ and are not part of this document — they change without
notice and a credential issued here cannot reach them.
The hosted MCP server at https://api.timetracker.live/api/mcp/ is the same
surface, spoken as tools. Most people will never touch the REST endpoints
below: they point an assistant at that address and approve it. This document is
for somebody writing their own program.
Programmatic access is a premium feature. Every endpoint below refuses an account without it, and says the subscription is the reason.
Two kinds reach this surface, and both are Authorization: Bearer <value>.
Made in the app: Settings → AI & API → Personal access tokens. Give it a name you will recognise, tick the permissions it needs, and create it.
The value is shown once. It is stored as a SHA-256 digest, so it cannot be recovered afterwards — not by you and not by us. Copy it when it appears. If it is lost, revoke it and make another.
Values look like tt_<43 url-safe characters>. The prefix is not a secret: it
exists so that a value found in a shell history or a log is recognisable as a
Timetracker credential and can be revoked rather than puzzled over.
An account may hold 20 live tokens. Revoking one leaves the others working, and revoking never needs a subscription — a credential nobody can end is worse than one nobody can use.
An assistant registers itself (RFC 7591), sends the person to Timetracker to approve it, and exchanges a one-time code for an access token. Nobody handles a credential by hand. This is what the MCP server uses; see §7.
Authorization: Bearer tt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
A request with no header, an unknown token, a malformed one or a revoked one is answered 401 with the same sentence in every case. That is deliberate: none of the four has a different remedy, and distinguishing them would turn the endpoint into an oracle about other people's credentials.
Four, coarse on purpose — a permission nobody can predict the effect of is a permission nobody reads before granting.
| Scope | What it allows |
|---|---|
time:read | Read tracked time, totals, what is running, goal progress |
time:write | Start, stop, switch, record a past stretch, correct one, divide one, remove one |
structure:read | Read activities, categories and goals |
structure:write | Create, change, delete and reorder them; change settings |
A request outside the credential's permissions is 403 with
code: insufficient_scope and a required_scope field naming the one that was
missing.
Every refusal carries a sentence and a code. The sentence is for the person reading a log at midnight; the code is for the program deciding what to do.
{ "error": "This credential was not given permission to do that.",
"code": "insufficient_scope",
"required_scope": "time:write" }
| Code | Status | What to do |
|---|---|---|
unauthenticated | 401 | The credential is unusable. Issue a new one. |
subscription_required | 403 | The account has no premium. Pay; change nothing else. |
insufficient_scope | 403 | Issue a credential with the scope named. |
rate_limited | 429 | Wait. Retry-After and the body both say how long. |
invalid_request | 400 / 409 | The request itself was wrong; the sentence says how. |
not_found | 404 | Nothing of that id belongs to this account. |
The four that matter are the first four, and telling them apart is the point: a script that cannot separate an absent subscription from a bad credential reissues a perfectly good token and is still refused.
Some refusals carry extra fields — conflicts on an overlapping write,
limit_days on an over-long period, field on a malformed parameter. They are
additive; a caller that ignores them still sees error and code.
Z — 2026-09-13T14:05:00Z. A
timestamp you send may carry any offset; it is understood and stored as an
instant.from=2026-09-12 means the
day that account's own screens call the 12th, whatever timezone your machine
sits in. Every period answer repeats back period.timezone so you can check.activity_id and category_id are
the numbers the person sees in the app; entry_id is global. A number is
never handed out twice, so a deleted activity's id stays retired.limit_days
rather than served slowly; ask for it in pieces.GET /api/v1/time/summary/ — time:readWhere a period went. This is the one to reach for: an assistant handed thousands of entries to answer "where did my week go" pays for them and answers worse.
| Parameter | |
|---|---|
from, to | YYYY-MM-DD, both inclusive. Give both or neither; neither means the account's own today. |
{
"period": { "from": "2026-09-07", "to": "2026-09-13", "timezone": "Europe/Lisbon" },
"total_minutes": 2841.5,
"uncategorised_minutes": 120.0,
"by_activity": [ { "activity_id": 4, "activity_name": "Writing", "minutes": 610.5 } ],
"by_category": [ { "category_id": 2, "category_name": "Work", "minutes": 1840.0 } ]
}
An activity attributed to several categories splits its minutes by the
percentages the person set, so by_category and by_activity do not have the
same rows and need not agree row for row. uncategorised_minutes is time on
activities in no category at all, published so that the categories plus it add
up to the total — otherwise a caller checking its own arithmetic finds a gap
and cannot tell whether it is a bug or a design.
GET /api/v1/time/entries/ — time:readThe individual stretches, a page at a time.
| Parameter | |
|---|---|
from, to | as above |
limit | 1–1000, default 500 |
offset | from 0 |
tag | a tag id; repeat it, or send tags=1,2, to mean "carrying any of these" |
{
"period": { "from": "2026-09-13", "to": "2026-09-13", "timezone": "Europe/Lisbon" },
"total": 12, "limit": 500, "offset": 0, "next_offset": null,
"entries": [ {
"entry_id": 91824, "activity_id": 4, "activity_name": "Writing",
"started_at": "2026-09-13T09:00:00Z", "ended_at": "2026-09-13T10:30:00Z",
"minutes": 90.0, "note": "chapter 3", "note_kept_with_activity": false,
"tags": [ { "tag_id": 3, "name": "deep work", "color": "#8b5cf6" } ],
"tags_kept_with_activity": false
} ]
}
An entry overlapping the window is reported clipped to it — started_at,
ended_at and minutes describe the part inside the period, while entry_id
is the whole entry's. A running entry has ended_at: null and is counted up to
now and no further. Page with next_offset until it is null.
Narrowing by tag is refused for an account that has tags switched off, or
whose subscription has lapsed — the stretches themselves are still returned
carrying the tags they have, because a tag is half of why two identical-looking
rows are two rows and hiding it would leave that unexplained.
GET /api/v1/time/current/ — time:read{ "running": { "entry_id": 91830, "activity_id": 4, "activity_name": "Writing",
"started_at": "2026-09-13T14:02:00Z", "minutes_so_far": 18.4,
"note": "", "note_kept_with_activity": false,
"tags": [], "tags_kept_with_activity": false } }
Nothing running answers { "running": null }, which is an ordinary answer
rather than a 404.
GET /api/v1/goals/progress/ — time:read| Parameter | |
|---|---|
period | day (default), week or month |
date | YYYY-MM-DD — any day inside the period wanted; defaults to today |
{
"period": { "type": "week", "from": "2026-09-07", "to": "2026-09-13",
"timezone": "Europe/Lisbon" },
"goals": [ { "activity_id": 4, "activity_name": "Writing",
"goal_type": "minimum", "target_minutes": 600,
"tracked_minutes": 610.5, "met": true } ]
}
goal_type is minimum, maximum or exact. An exact goal counts as met
within a minute either way — a person cannot hit a target to the second.
time:writeTwo places this surface is deliberately stricter than the app, and both come from the same fact: a program cannot see the screen.
POST /api/v1/time/start/{ "activity_id": 4 }
→ 201 { "running": {…}, "already_running": false }
Refused while a different activity is running (400), and the refusal names
what is running. The app's own start would silently end it, which is fine for a
thumb on a tile and unrecoverable for an assistant acting on a misheard
sentence. Use switch to replace one.
Starting the activity that is already running changes nothing and answers
200 with already_running: true — so a request whose answer was lost can be
repeated without cutting one session into two.
POST /api/v1/time/stop/→ { "stopped": {…} }
Nothing running is a 400, not an empty 200: a program that asked to stop something and got a 200 would reasonably conclude it had recorded a stretch. A session too short to keep is discarded rather than stored, and that is also a 400 saying so.
POST /api/v1/time/switch/{ "activity_id": 7 }
→ { "stopped": {…} | null, "running": {…} }
One act, no gap between the two. stopped is null when the previous session
was too short to keep and its activity was changed in place — there is no
stretch to go looking for.
POST /api/v1/time/entries/record/A stretch that was not tracked while it happened.
{ "activity_id": 4,
"started_at": "2026-09-13T13:00:00Z",
"ended_at": "2026-09-13T14:00:00Z",
"note": "planning call",
"note_kept_with_activity": false }
→ 201 { "entry": {…}, "merged_entry_ids": [91823] }
Refused if it would overlap time already recorded, and the refusal names what it clashed with:
{ "error": "That time overlaps something already recorded. Nothing was changed.",
"code": "invalid_request",
"conflicts": [ { "entry_id": 91823, "activity_id": 7, "activity_name": "Email" } ] }
Touching is not overlapping — a stretch beginning exactly where another ends is accepted. Also refused: an end not after the start, anything shorter than a second, and anything in the future (a caller whose clock runs a few seconds ahead is pulled back to now rather than refused; beyond that the clock is wrong rather than drifting).
merged_entry_ids names entries that no longer exist because this one absorbed
them: two touching stretches of one activity whose notes match are one
entry. That is why notes are part of what an entry is, and why a caller that
writes notes changes when entries merge.
PATCH /api/v1/time/entries/<entry_id>/Every field optional; what you do not name keeps its value. Name at least one.
{ "activity_id": 7, "started_at": "…", "ended_at": "…",
"note": "", "note_kept_with_activity": true,
"tags": [3, 5], "tags_kept_with_activity": true }
→ { "entry": {…}, "merged_entry_ids": [], "removed_entry_ids": [] }
An absent note leaves the note alone; "" clears it. tags behaves the same
way: absent keeps the ones the stretch has, [] takes them all off. A
running entry stays running — setting ended_at on one is refused, because stopping it is a
different act with its own endpoint.
POST /api/v1/time/entries/<entry_id>/split/Divide one recorded stretch in two at a moment, because part of it was something else. The later part carries the activity you name; the earlier one keeps what it had unless you say otherwise, which you can — both halves are described in one call.
{ "at": "2026-09-13T13:30:00Z", "activity_id": 7, "note": "the standup",
"tags": [5],
"first_activity_id": 4, "first_note": "chapter 3", "first_tags": [3] }
The three first_* fields are optional and each is independent: absent means
"leave that part of the earlier half exactly as it is", which is what every
caller written before they existed sends. They exist because between two
requests the two halves are identical, so the merge folds them straight back
together and a second request has nothing left to edit.
→ { "first_entry": {…}, "second_entry": {…}, "merged_entry_ids": [] }
note is for the later part and defaults to empty: a division asserts that
the later part was different work, so carrying the earlier half's words across
would put them in somebody's mouth. tags defaults the other way and the
later part keeps the ones the stretch had — a tag says what kind of occasion it
was, which the division does not contradict. Send [] to strip them.
Dividing the running entry leaves the later part running, so the account is tracking the activity you named afterwards.
Refused when the moment is at or outside the entry's own ends, when either part would be shorter than a second (the refusal says which part), and when the two parts would end up alike in activity, note and tags — those would be merged back into one on the spot, and the answer would then describe two stretches where one exists. So one activity divided by two different notes, or by two different tag sets, is a legal and useful shape.
There is no selected_date here, unlike the endpoint the app's own screens
call. That parameter means "the row the person clicked belonged to this day",
which a program has no way to mean. A division cuts the named entry whole,
however many days it spans; to divide only one day's part, divide and then
correct one of the halves.
DELETE /api/v1/time/entries/<entry_id>/Remove a stretch altogether. → 204, no body.
Afterwards it counts towards no total, no report and no goal. There is no undo.
Nothing is merged. The time simply becomes empty, and two stretches of one activity left touching by the removal stay two stretches — the one place in this product where touching entries of one activity are not joined. Removing says "this did not happen", not "the time around it was one continuous thing", and a removal that quietly rewrote two neighbours would destroy more than the row it was asked about.
Removing the running entry leaves the account tracking nothing.
No confirmation step, unlike deleting an activity (§7). The boundary is the cascade rather than the severity: an operation that can destroy more than the thing named is worth a preview, and one that destroys exactly the thing named is not.
An account keeps a list of tags and puts up to five of them on a stretch, as
a second axis over the same minutes. tags on record and correct, and
tags / first_tags on split, all take tag ids from GET /api/v1/tags/
— a tag has to exist before it can be used, and a name that is not there yet is
made with POST /api/v1/tags/.
The tag set is half of what makes a stretch distinct. Two neighbouring stretches of one activity are joined into one only where their notes and their tags match, so putting a tag on one of them keeps them apart and taking it off again merges them — irreversibly, like every other merge in this product.
Writing tags is refused while the account has tags switched off, naming the setting; §7 is how you turn it on. Reading them never is.
At most 500 characters (characters, not bytes — Cyrillic costs the same as Latin here). Line breaks are kept. A note written while the account has notes switched off is refused naming the setting; §8 is how you turn it on.
structure:read / structure:writeGET /api/v1/activities/{ "activities": [ {
"activity_id": 4, "name": "Writing", "icon": "✍️", "color": "#8b5cf6",
"trackable": true, "parent_id": null,
"categories": [ { "category_id": 2, "category_name": "Work", "percentage": 100 } ],
"goal": { "goal_type": "minimum", "target_minutes": 600,
"period_type": "weekly", "custom_schedule": {…} }
} ] }
In the order the person arranged them, not alphabetically and not by id.
POST /api/v1/activities/ · PATCH /api/v1/activities/<id>/The same body. Percentages must total exactly 100 across the categories named,
each 1–100, no category twice, all of them yours. parent_id nests one activity
under another; cycles are refused. goal: null removes a goal; omitting the key
leaves it alone.
Goal period_type is daily, workday, weekend, weekly or monthly. The
last two require a custom_schedule and the first three refuse one.
GET /api/v1/activities/<id>/ — what a deletion would cost{ "activity_count": 3, "entry_count": 214, "minutes": 18402.5 }
DELETE /api/v1/activities/<id>/?confirm=trueWithout confirm=true this deletes nothing and answers 409 with the
preview above. There is no undo anywhere in this product, and an assistant
acting on a misheard sentence is exactly the caller that arrives here.
Deleting takes everything nested under it — the count above says how much.
POST /api/v1/activities/<id>/move/{ "parent_id": null, "position": 2 }
position is 0-based among the siblings at the destination. Answers the whole
list in its new order.
GET/POST /api/v1/categories/, PATCH/DELETE /api/v1/categories/<id>/,
POST /api/v1/categories/<id>/move/ ({"position": 1}). A category still
attributed to a visible activity is not deleted; the refusal says how many.
{ "categories": [ { "category_id": 2, "name": "Work", "color": "#0ea5e9" } ] }
GET/POST /api/v1/tags/, PATCH/DELETE /api/v1/tags/<id>/. Reading needs
structure:read, changing needs structure:write — a tag is a word the account
keeps, not time it spent.
{ "tags": [ { "tag_id": 3, "name": "deep work", "color": "#8b5cf6" } ] }
A name is at most 30 characters, and two tags of one account never share one ignoring case; the refusal names the tag it clashed with. A colour left out is chosen from the same palette activities use.
GET /api/v1/tags/<id>/ answers what deleting it would cost without deleting
anything:
{ "tag_id": 3, "name": "deep work", "color": "#8b5cf6",
"entry_count": 41, "would_join_entries": 2 }
would_join_entries is the number nobody expects. Removing a tag takes it off
every stretch carrying it, and where that tag was the only thing telling two
neighbouring stretches of one activity apart, the two become one. No recorded
time is lost either way, and there is no undo.
DELETE needs no confirm=true — it destroys a label rather than recorded
time, which is the boundary §6 draws for removing a stretch — and answers
{ "deleted": true, "entries_changed": 41, "merged_entry_ids": [91824] }.
GET / PATCH /api/v1/settings/ — structure:write{ "notes_enabled": true, "tags_enabled": true, "timezone": "Europe/Lisbon" }
notes_enabled and tags_enabled are writable; timezone is read-only here.
They exist so that a caller refused for writing a note or a tag while those are
off has a way forward that is not "open the app". tags_enabled reports what
the person set; whether tags are actually in force is that and a live
subscription (§9).
One address: https://api.timetracker.live/api/mcp/. Streamable HTTP,
JSON-RPC, protocol revision 2026-07-28.
Nobody pastes a token into it. An assistant discovers the authorization
server from WWW-Authenticate on its first unauthenticated request, registers
itself, sends the person to Timetracker to approve, and exchanges the code. The
metadata lives at the host root, where assistants look for it:
GET /.well-known/oauth-protected-resource (RFC 9728)GET /.well-known/oauth-authorization-server (RFC 8414)POST /api/oauth/register/ (RFC 7591), /api/oauth/authorize/,
/api/oauth/token/PKCE (S256) is required, not offered. The redirect URI is fixed at
registration. An authorization code is used once, quickly, and only by the
client it was issued to — a reused code is treated as evidence that it leaked,
and the tokens it produced are ended.
Twenty-five, and they are meaningful actions rather than one tool per endpoint — an assistant choosing between twenty-odd endpoints chooses badly.
Every write in this document has one behind it, with a single deliberate exception noted below. That is asserted by a test rather than remembered: for a day after this server first shipped it could start, stop, switch and record while the REST surface could already correct an entry, so an assistant asked to move a running entry's start back two minutes answered that it had no tool for it — true of the server and false of the product.
| Tool | Scope |
|---|---|
where_my_time_went | time:read |
list_time_entries | time:read |
goal_progress | time:read |
what_is_running | time:read |
list_activities | structure:read |
list_categories | structure:read |
list_tags | structure:read |
start_tracking | time:write |
stop_tracking | time:write |
switch_activity | time:write |
record_past_time | time:write |
correct_entry | time:write |
split_entry | time:write |
delete_entry | time:write |
create_activity | structure:write |
update_activity | structure:write |
move_activity | structure:write |
delete_activity | structure:write |
create_category | structure:write |
update_category | structure:write |
move_category | structure:write |
delete_category | structure:write |
create_tag | structure:write |
update_tag | structure:write |
delete_tag | structure:write |
Four of them are worth a sentence each:
correct_entry is also how an activity is changed. There is no separate
re-aiming action: two ways to do one thing is how an assistant picks the
wrong one.delete_activity keeps its two steps. Called without confirm, it
removes nothing and answers what would be lost — how many activities, how
many stretches, how many minutes — so the assistant can put those numbers to
the person before anything goes.delete_entry has no such step, and says in its own description that it
cannot be undone. A guard on every destructive call is a guard nobody reads.delete_tag keeps the two steps, unlike the REST endpoint under it,
because its second number is the surprising one: called without confirm it
answers how many stretches carry the tag and how many would be JOINED by
losing it, so the assistant can say that out loud before anything goes.The account's settings are the one published write with no action behind it.
Changing a timezone or turning notes off changes every reading that follows it,
and nobody asks for that out loud. Use PATCH /api/v1/settings/ directly.
An action the connection was not granted is refused with the missing permission named; an account whose subscription has lapsed is refused as a subscription problem, not as a broken connection.
Settings → AI & API carries the address, a copy control, the steps for each assistant, and examples worth asking. Connections are listed there and withdrawn there. Withdrawing ends every credential inside the connection at once.
Credentials go dormant, not revoked. Tokens and connections stay exactly
where they are; requests are refused with subscription_required; and when the
subscription comes back everything works again with nothing changed on the
caller's side. Revoking a token and withdrawing a connection keep working
throughout — those never need premium.
v1 is a promise. What may change inside it:
What will not change inside v1: the meaning of a field, the name of a field,
the shape of an answer, or the conditions under which a request is refused.
Anything that would is a v2.