Timetracker API reference

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.


1. Getting a credential

Two kinds reach this surface, and both are Authorization: Bearer <value>.

Personal access tokens — for software you run yourself

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.

OAuth — for software acting on somebody's behalf

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.

Presenting it

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.


2. Permissions

Four, coarse on purpose — a permission nobody can predict the effect of is a permission nobody reads before granting.

ScopeWhat it allows
time:readRead tracked time, totals, what is running, goal progress
time:writeStart, stop, switch, record a past stretch, correct one, divide one, remove one
structure:readRead activities, categories and goals
structure:writeCreate, 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.


3. Refusals

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" }
CodeStatusWhat to do
unauthenticated401The credential is unusable. Issue a new one.
subscription_required403The account has no premium. Pay; change nothing else.
insufficient_scope403Issue a credential with the scope named.
rate_limited429Wait. Retry-After and the body both say how long.
invalid_request400 / 409The request itself was wrong; the sentence says how.
not_found404Nothing 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.


4. Conventions

  • JSON in, JSON out. No other shape is offered.
  • Instants are ISO 8601 in UTC, ending Z — 2026-09-13T14:05:00Z. A timestamp you send may carry any offset; it is understood and stored as an instant.
  • Dates are the account's, not the caller's. 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.
  • Durations are minutes, rounded to one decimal.
  • Ids are per-account and start at 1. 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.
  • Rate limit: 120 requests a minute per account, not per credential — ten tokens are still one subscriber.
  • A period may not exceed 366 days. Longer is refused with limit_days rather than served slowly; ask for it in pieces.

5. Reading time

GET /api/v1/time/summary/ — time:read

Where 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, toYYYY-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:read

The individual stretches, a page at a time.

Parameter
from, toas above
limit1–1000, default 500
offsetfrom 0
taga 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
periodday (default), week or month
dateYYYY-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.


6. Writing time — time:write

Two 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.

Tags

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.

Notes

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.


7. Activities, categories and goals — structure:read / structure:write

GET /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=true

Without 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.

Categories

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" } ] }

Tags

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).


8. The MCP server

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.

The tools

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.

ToolScope
where_my_time_wenttime:read
list_time_entriestime:read
goal_progresstime:read
what_is_runningtime:read
list_activitiesstructure:read
list_categoriesstructure:read
list_tagsstructure:read
start_trackingtime:write
stop_trackingtime:write
switch_activitytime:write
record_past_timetime:write
correct_entrytime:write
split_entrytime:write
delete_entrytime:write
create_activitystructure:write
update_activitystructure:write
move_activitystructure:write
delete_activitystructure:write
create_categorystructure:write
update_categorystructure:write
move_categorystructure:write
delete_categorystructure:write
create_tagstructure:write
update_tagstructure:write
delete_tagstructure: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.

Connecting, in the app

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.


9. What happens when a subscription ends

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.


10. Versioning

v1 is a promise. What may change inside it:

  • New fields may appear in any response. Ignore what you do not recognise.
  • New endpoints and new tools may be added.
  • New refusal codes may appear; treat an unknown code by its HTTP status.

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.