Taskr API v1, from a script and from an AI assistant

Everything the interface can do to your workspace has a token-authenticated REST API behind it: workspaces, lists, tasks, notes, tracked time, statistics and stored files. There are two doors into the same surface — write the automation yourself against https://taskr.cc/api/v1, or let an AI assistant drive exactly the same endpoints as MCP tools. Both read one registry, so an endpoint cannot exist in one door and be missing in the other.

API access is part of Premium Plus and Team. Free and Premium accounts see an upgrade panel on the API settings tab instead of the token list, and every API call from such an account answers 403 plan_required with a link to the plans.

Before your first call

A plan with API access (Premium Plus or Team) on the account that owns the token.
A verified email. An unverified credentials account cannot write through the API — the same rule the app applies to any write.
A realistic expectation of what a token can do. A token is not a separate identity: it acts as the person who created it. Workspace roles still apply (a VIEWER token cannot edit tasks), quotas and limits are still checked against the workspace owner's plan, and if that plan loses API access — a downgrade, an expired subscription — the token stops working on the next request.

1. Create a token

Open Settings → API (/settings?tab=api) and press Create token. The dialog asks for three things:

Field	What to pick
Name	A label you will recognise in the list later — `Hermes`, `deploy-script`, `weekly-invoice`. It is not a username; it changes nothing about what the token can do.
Scope	Read only (`read`) can list workspaces, lists, tasks, notes, statistics and files. Read and write (`read` + `write`) can additionally create, update and complete tasks and lists, write notes, start and stop timers and upload files. `write` implies `read`.
Expires	`Never`, or 30 / 90 / 365 days. An expired token stops authenticating on its own and stops counting against your token limit.

Copy the token immediately. The plaintext (tk_live_…) is shown exactly once, in the confirmation dialog. The database stores only a hash of it, and the list afterwards shows just the prefix (tk_live_ab12…), the scopes, when it was created and when it was last used. If you lose it, revoke it and create another one — there is nothing to recover.

Revoking is immediate. The row stays in the list, greyed out as REVOKED, and the very next request with that token answers 401. Dead tokens (revoked or expired) are kept for 30 days so you can still see what you switched off, then removed automatically.

One account can hold 10 usable tokens at a time — revoked and expired ones do not count. The Create token button refuses before the dialog opens once you are at the cap, with an Upgrade plan link in the toast; the API answers 403 limit_reached.

2. Your first call

Put the token in an environment variable rather than in your shell history:

export TASKR_TOKEN="tk_live_…"

curl -s https://taskr.cc/api/v1/me \
  -H "Authorization: Bearer $TASKR_TOKEN"

curl -s https://taskr.cc/api/v1/workspaces \
  -H "Authorization: Bearer $TASKR_TOKEN"

GET /me answers with who the token belongs to (user), the token itself as metadata (prefix, scopes, expiresAt, lastUsedAt — never the token), the plan (tier, mcpApi, limits) and the two rate-limit budgets every call is checked against, so a client never has to guess its headroom.

GET /workspaces is where every other call starts, because almost every endpoint needs a workspace id. It returns the workspaces you own or belong to, with your role in each and counters for lists, tasks, notes and other members.

If that returned data, you are done — the rest is reading the endpoint list at the bottom of this page and calling it. A 401 means the token is missing, malformed, revoked or expired; a 403 plan_required means the account's plan has no API access; a 429 carries Retry-After.

3. What the API can and cannot do

Can: read workspaces; create, rename, reorder and delete lists; create, edit, complete, reopen, move and delete tasks; add subtasks; read and write notes; search across a workspace; resolve a pasted id to the thing it names; read statistics for tasks, lists and tracked time; start and stop the time tracker; list, upload and delete stored files.

Cannot, in v1: create workspaces, invite or manage members, change roles, touch billing or account settings, or read your notification history. Those live in the interface only — deliberately, because they are the decisions a person should be making by hand. If you need one of them automated, say so; the list of what is worth opening up is short and driven by what people actually ask for.

4. Conventions worth knowing before you write code

Pagination. List endpoints take limit (1–200, default 50) and cursor, and answer { "data": [ … ], "nextCursor": "…" }. nextCursor is null on the last page; it is an opaque keyset cursor, so never build one yourself. Rows are ordered newest first. search is the exception — it caps matches per type instead of paging.
Ids travel in a paste-ready form. Every id parameter accepts the bare id the API returns and a reference — the same id with a type prefix: taskr_w_… (workspace), taskr_l_… (list), taskr_t_… (task), taskr_n_… (note). The app's copy buttons put the prefixed form on your clipboard, so an id lifted off the board can be pasted straight into a request. A prefix is an alias, never a permission: a reference to someone else's row answers the same 404 a bare id does.
Ids you cannot see answer 404, not 403. A foreign workspace, another person's private note and a genuinely missing id are indistinguishable by design — otherwise the API would tell a stranger which ids exist. Never branch your client on 403 vs 404 to learn whether something is real; both mean "not available to you".
Deletes behave like the interface. A deleted list or task is soft-deleted: it stays in the database with its real name and a deleted: true flag, and is hidden from reads unless you ask for it (list_lists takes includeDeleted=true). Statistics are the one place where soft-deleted tasks still appear, so tracked hours stay attributable.
List rows stay small. list_tasks truncates text at 500 characters and tells you there is a description; the full markdown is on get_task alone. Same for notes: list_notes carries a short preview, get_note carries the body. A page of 200 rows must never be able to ship megabytes.
Notes keep their rules. A private note is visible only to its author (404 for everyone else), and a locked note refuses content writes with 403.
Writes update open boards, and never your phone. An API write emits the same realtime event and workspace activity entry the app emits, so a board someone is watching updates without a refresh. It deliberately sends no push notification and no notification row — an agent writing in bulk must not ring anybody.
and are inclusive day keys () in your timezone and default to the last 90 days. OWNER/MODERATOR see the whole workspace, VIEWER/EDITOR only their own tracked time, and the answer says which applied.

5. Answers and limits you will run into

Every failure, on every endpoint, comes back in one envelope, and requestId is what to quote if you need help:

{
  "error": {
    "code": "not_found",
    "message": "Task not found",
    "requestId": "req_9f3c1a0b7d2e4c88"
  }
}

`code`	HTTP	Meaning
`invalid_input`	400	The body or query failed validation; `error.details` names the offending field.
`unauthorized`	401	Missing, malformed, revoked or expired token.
`forbidden`	403	Your role in that workspace does not allow the action (a locked note answers this too).
`plan_required`	403	The plan gates it: no API access, no time tracking, or a plan limit for the resource is reached. `error.details.upgradeUrl` says where to fix it.
`not_found`	404	Does not exist, or is not visible to this token.
`conflict`	409	Conflicts with the current state — tracking a completed task, for instance.
`payload_too_large`	413	Over the body ceiling: 1 MiB of JSON, 6 MiB for an upload, 7.67 MiB for one MCP request.
`rate_limited`	429	A budget is exhausted. Honour `Retry-After`.
`internal`	500	Something broke on our side; details are never exposed. Quote the `requestId`.

Rate limits are two budgets plus one fuse. Every request is checked against the token's own budget (600 requests available immediately, then a sustained 10/s) and the account's budget (1200 immediately, then 10/s, shared by every token on the account). A separate, much higher per-IP fuse sits in front of both, and a stream of failed authentication from one address is throttled on its own budget (60 refusals per minute) so that guessing at tokens stops being cheap.

Both budgets are on every answer, so you never have to guess which one refused you — the family whose Remaining reached 0 is the one that did:

Header	Meaning
`X-RateLimit-Token-Limit` / `-Remaining` / `-Reset`	This token's budget (600, refilling 10/s).
`X-RateLimit-Account-Limit` / `-Remaining` / `-Reset`	The account's budget, shared by all its tokens (1200, refilling 10/s).
`X-RateLimit-Failure-*`	The per-IP refusal budget (60/min, refilling 1/s).
`Retry-After`	Present on every `429` from those budgets.

Read them as token buckets rather than "N per minute": 600 now, then 10/s. Creating another token gives that new token its own 600 — it does not add to the account's shared 1200, so minting tokens to get more throughput does not work. Plan for the sustained rate: an IDE client plus a cron job never comes near the ceiling, a loop that hammers the API will meet it.

Every response also carries X-Request-Id and Cache-Control: no-store. Refusals by the plan or scope gate carry no budget headers at all, because nothing was counted yet — and a 401 carries none either, on purpose: an unauthenticated caller should not be able to measure your budgets.

6. Handing the same surface to an AI assistant

The whole API is available as MCP tools: one tool per endpoint, with the same names, schemas, scopes and gates. There is nothing to install for the hosted endpoint — add a URL and your token:

// Claude Code (.mcp.json) and Cursor (~/.cursor/mcp.json) — same name, same token
{
  "mcpServers": {
    "taskr": {
      "type": "http",
      "url": "https://taskr.cc/api/mcp",
      "headers": { "Authorization": "Bearer tk_live_…" }
    }
  }
}

# Hermes — ~/.hermes/config.yaml
mcp_servers:
  taskr:
    url: "https://taskr.cc/api/mcp"
    headers:
      Authorization: "Bearer tk_live_…"

The endpoint is stateless — one server per request, no session, no sticky routing — so it works behind any proxy, and a plain HTTP client is enough to speak to it. Four things worth knowing:

A tool call costs what a REST call costs. The protocol request authenticates once and every tool call inside it is a full API call, so budget roughly half the requests of the same token's REST allowance when each request carries a call.
Keep one call under two minutes. A single call that takes longer than the edge's read timeout (125 s) is cut off with a 524. Long aggregates belong in a REST job you poll.
MCP passes the same gates. A read token can list the tools and is refused, per call, on every write tool — exactly as over REST. Free and Premium accounts get 403 plan_required.
A local stdio server exists too, for development against this repository (mcp/), but it is not published to npm yet, so there is no npx -y @taskr/mcp to install. Use the hosted endpoint.

Every endpoint, generated from the API itself

The list below is grouped the way you would look for something. It is not written by hand: it is rendered from the API's own registry while this page is built, so it cannot describe an endpoint that does not exist, and it keeps up with a new one without anyone remembering to update a table.

Endpoint What it does

GET /_toolsreadlist_tools List every tool this API exposes, with its REST method and path, its input JSON Schema, the required token scope and whether it is destructive. An MCP client calls this once at startup to register its tools, so a newly added endpoint needs no client update. Requires a read scope; the plan gate applies.

GET /mereadget_me Return the identity behind the API token: the calling user, the token's prefix and scopes, its expiry, the plan tier with its limits, and the two rate-limit budgets every call is checked against — the per-token one and the per-account one that all of the account's tokens share. Use it first to confirm which account a token belongs to, and to size concurrency without guessing. It never returns the token itself.

Endpoint	What it does
`GET /_tools`readlist_tools	List every tool this API exposes, with its REST method and path, its input JSON Schema, the required token scope and whether it is destructive. An MCP client calls this once at startup to register its tools, so a newly added endpoint needs no client update. Requires a `read` scope; the plan gate applies.
`GET /me`readget_me	Return the identity behind the API token: the calling user, the token's prefix and scopes, its expiry, the plan tier with its limits, and the two rate-limit budgets every call is checked against — the per-token one and the per-account one that all of the account's tokens share. Use it first to confirm which account a token belongs to, and to size concurrency without guessing. It never returns the token itself.

Endpoint What it does

GET /workspacesreadlist_workspaces List the workspaces the token's user owns or belongs to, newest first. Use it first: every other tool needs a workspace id, and this is where you get one. Each entry carries the caller's role/isOwner and the counters lists/tasks/notes/members — counts only notes the caller may see, and exclude soft-deleted rows, and counts collaborators OTHER than the owner (the owner has no membership row, so 0 means the workspace is not shared). Only workspaces the caller may access are returned; a foreign workspace is simply absent. is truncated at 500 characters in list entries — returns the stored value. Paginate with the opaque until is null.

Endpoint	What it does
`GET /workspaces`readlist_workspaces	List the workspaces the token's user owns or belongs to, newest first. Use it first: every other tool needs a workspace id, and this is where you get one. Each entry carries the caller's role/isOwner and the counters lists/tasks/notes/members — counts only notes the caller may see, and exclude soft-deleted rows, and counts collaborators OTHER than the owner (the owner has no membership row, so 0 means the workspace is not shared). Only workspaces the caller may access are returned; a foreign workspace is simply absent. is truncated at 500 characters in list entries — returns the stored value. Paginate with the opaque until is null.

Taskr API v1, from a script and from an AI assistant

Before your first call

A plan with API access (Premium Plus or Team) on the account that owns the token.
A verified email. An unverified credentials account cannot write through the API — the same rule the app applies to any write.
A realistic expectation of what a token can do. A token is not a separate identity: it acts as the person who created it. Workspace roles still apply (a VIEWER token cannot edit tasks), quotas and limits are still checked against the workspace owner's plan, and if that plan loses API access — a downgrade, an expired subscription — the token stops working on the next request.

1. Create a token

Open Settings → API (/settings?tab=api) and press Create token. The dialog asks for three things:

Field	What to pick
Name	A label you will recognise in the list later — `Hermes`, `deploy-script`, `weekly-invoice`. It is not a username; it changes nothing about what the token can do.
Scope	Read only (`read`) can list workspaces, lists, tasks, notes, statistics and files. Read and write (`read` + `write`) can additionally create, update and complete tasks and lists, write notes, start and stop timers and upload files. `write` implies `read`.
Expires	`Never`, or 30 / 90 / 365 days. An expired token stops authenticating on its own and stops counting against your token limit.

2. Your first call

Put the token in an environment variable rather than in your shell history:

export TASKR_TOKEN="tk_live_…"

curl -s https://taskr.cc/api/v1/me \
  -H "Authorization: Bearer $TASKR_TOKEN"

curl -s https://taskr.cc/api/v1/workspaces \
  -H "Authorization: Bearer $TASKR_TOKEN"

3. What the API can and cannot do

4. Conventions worth knowing before you write code

Pagination. List endpoints take limit (1–200, default 50) and cursor, and answer { "data": [ … ], "nextCursor": "…" }. nextCursor is null on the last page; it is an opaque keyset cursor, so never build one yourself. Rows are ordered newest first. search is the exception — it caps matches per type instead of paging.
Ids travel in a paste-ready form. Every id parameter accepts the bare id the API returns and a reference — the same id with a type prefix: taskr_w_… (workspace), taskr_l_… (list), taskr_t_… (task), taskr_n_… (note). The app's copy buttons put the prefixed form on your clipboard, so an id lifted off the board can be pasted straight into a request. A prefix is an alias, never a permission: a reference to someone else's row answers the same 404 a bare id does.
Ids you cannot see answer 404, not 403. A foreign workspace, another person's private note and a genuinely missing id are indistinguishable by design — otherwise the API would tell a stranger which ids exist. Never branch your client on 403 vs 404 to learn whether something is real; both mean "not available to you".
Deletes behave like the interface. A deleted list or task is soft-deleted: it stays in the database with its real name and a deleted: true flag, and is hidden from reads unless you ask for it (list_lists takes includeDeleted=true). Statistics are the one place where soft-deleted tasks still appear, so tracked hours stay attributable.
List rows stay small. list_tasks truncates text at 500 characters and tells you there is a description; the full markdown is on get_task alone. Same for notes: list_notes carries a short preview, get_note carries the body. A page of 200 rows must never be able to ship megabytes.
Notes keep their rules. A private note is visible only to its author (404 for everyone else), and a locked note refuses content writes with 403.
Writes update open boards, and never your phone. An API write emits the same realtime event and workspace activity entry the app emits, so a board someone is watching updates without a refresh. It deliberately sends no push notification and no notification row — an agent writing in bulk must not ring anybody.
and are inclusive day keys () in your timezone and default to the last 90 days. OWNER/MODERATOR see the whole workspace, VIEWER/EDITOR only their own tracked time, and the answer says which applied.

5. Answers and limits you will run into

Every failure, on every endpoint, comes back in one envelope, and requestId is what to quote if you need help:

{
  "error": {
    "code": "not_found",
    "message": "Task not found",
    "requestId": "req_9f3c1a0b7d2e4c88"
  }
}

`code`	HTTP	Meaning
`invalid_input`	400	The body or query failed validation; `error.details` names the offending field.
`unauthorized`	401	Missing, malformed, revoked or expired token.
`forbidden`	403	Your role in that workspace does not allow the action (a locked note answers this too).
`plan_required`	403	The plan gates it: no API access, no time tracking, or a plan limit for the resource is reached. `error.details.upgradeUrl` says where to fix it.
`not_found`	404	Does not exist, or is not visible to this token.
`conflict`	409	Conflicts with the current state — tracking a completed task, for instance.
`payload_too_large`	413	Over the body ceiling: 1 MiB of JSON, 6 MiB for an upload, 7.67 MiB for one MCP request.
`rate_limited`	429	A budget is exhausted. Honour `Retry-After`.
`internal`	500	Something broke on our side; details are never exposed. Quote the `requestId`.

Both budgets are on every answer, so you never have to guess which one refused you — the family whose Remaining reached 0 is the one that did:

Header	Meaning
`X-RateLimit-Token-Limit` / `-Remaining` / `-Reset`	This token's budget (600, refilling 10/s).
`X-RateLimit-Account-Limit` / `-Remaining` / `-Reset`	The account's budget, shared by all its tokens (1200, refilling 10/s).
`X-RateLimit-Failure-*`	The per-IP refusal budget (60/min, refilling 1/s).
`Retry-After`	Present on every `429` from those budgets.

6. Handing the same surface to an AI assistant

The whole API is available as MCP tools: one tool per endpoint, with the same names, schemas, scopes and gates. There is nothing to install for the hosted endpoint — add a URL and your token:

// Claude Code (.mcp.json) and Cursor (~/.cursor/mcp.json) — same name, same token
{
  "mcpServers": {
    "taskr": {
      "type": "http",
      "url": "https://taskr.cc/api/mcp",
      "headers": { "Authorization": "Bearer tk_live_…" }
    }
  }
}

# Hermes — ~/.hermes/config.yaml
mcp_servers:
  taskr:
    url: "https://taskr.cc/api/mcp"
    headers:
      Authorization: "Bearer tk_live_…"

The endpoint is stateless — one server per request, no session, no sticky routing — so it works behind any proxy, and a plain HTTP client is enough to speak to it. Four things worth knowing:

A tool call costs what a REST call costs. The protocol request authenticates once and every tool call inside it is a full API call, so budget roughly half the requests of the same token's REST allowance when each request carries a call.
Keep one call under two minutes. A single call that takes longer than the edge's read timeout (125 s) is cut off with a 524. Long aggregates belong in a REST job you poll.
MCP passes the same gates. A read token can list the tools and is refused, per call, on every write tool — exactly as over REST. Free and Premium accounts get 403 plan_required.
A local stdio server exists too, for development against this repository (mcp/), but it is not published to npm yet, so there is no npx -y @taskr/mcp to install. Use the hosted endpoint.

Every endpoint, generated from the API itself

Endpoint What it does

Endpoint	What it does
`GET /_tools`readlist_tools	List every tool this API exposes, with its REST method and path, its input JSON Schema, the required token scope and whether it is destructive. An MCP client calls this once at startup to register its tools, so a newly added endpoint needs no client update. Requires a `read` scope; the plan gate applies.
`GET /me`readget_me	Return the identity behind the API token: the calling user, the token's prefix and scopes, its expiry, the plan tier with its limits, and the two rate-limit budgets every call is checked against — the per-token one and the per-account one that all of the account's tokens share. Use it first to confirm which account a token belongs to, and to size concurrency without guessing. It never returns the token itself.

Endpoint	What it does
`GET /workspaces`readlist_workspaces	List the workspaces the token's user owns or belongs to, newest first. Use it first: every other tool needs a workspace id, and this is where you get one. Each entry carries the caller's role/isOwner and the counters lists/tasks/notes/members — counts only notes the caller may see, and exclude soft-deleted rows, and counts collaborators OTHER than the owner (the owner has no membership row, so 0 means the workspace is not shared). Only workspaces the caller may access are returned; a foreign workspace is simply absent. is truncated at 500 characters in list entries — returns the stored value. Paginate with the opaque until is null.

Endpoint	What it does
`DELETE /lists/:listId`writeremoves datadelete_list	Soft-delete one list together with every task inside it. NOTHING IS ERASED: the list and its tasks keep their real names and gain a `deletedAt` timestamp, so tracked time and statistics that reference them stay readable, and `list_lists` with `includeDeleted=true` still shows the list flagged `deleted: true`. Any active timer running on the list is discarded, the remaining lists are renumbered, and every open board of the workspace — the caller's own included — is told to drop the list in realtime. Requires the OWNER or MODERATOR role (`canManageLists`); a VIEWER or EDITOR is refused with 403 and a list id that is unknown, already deleted or in another workspace answers 404. Use the exact `id` from `list_lists`. There is no undelete endpoint, and no push notification or activity entry is produced — confirm with the user before calling this on a list with tracked time.
`PATCH /lists/:listId`writeupdate_list	Update one list: rename it, change its description/date/time, move it on the board (`order`), or flip its shared collapse state. Send ONLY the fields you want to change — omitted fields keep their value, while an explicit null clears `description`, `date` or `time`. PERMISSIONS: `collapsed` and `finishedCollapsed` are shared VIEW STATE that ANY member (VIEWER and EDITOR included) may change, because that is what the board's collapse/expand button does; every other field requires the OWNER or MODERATOR role and a caller without `canManageLists` who sends one gets 403 — so an EDITOR can collapse a list through this API, but not rename it. A list id that is unknown, soft-deleted, or belongs to another workspace answers 404 (never 403), so the API cannot be used to discover other tenants' lists. Returns the updated list in the `list_lists` shape.
`GET /workspaces/:id/lists`readlist_lists	List the lists of a workspace, newest first, with the number of non-deleted tasks in each (`taskCount`). Soft-deleted lists are excluded by default; pass `includeDeleted=true` to see them as well — a deleted list keeps its REAL name and is marked `deleted: true` (never a placeholder name), so history stays readable. Deleted rows also carry a non-null `deletedAt`. Use a list id as `listId` when reading tasks (`list_tasks`) or creating tasks. Every member of the workspace sees every list. Paginate with the opaque `cursor` until `nextCursor` is null.
`POST /workspaces/:id/lists`writecreate_list	Create a list (a section/column of the board) at the END of one workspace's board and return the new list in the same shape `list_lists` uses. Use the returned `id` as `listId` when creating tasks. Requires the OWNER or MODERATOR role (`canManageLists`, the same role the in-app Add-List action requires) and is refused with 403 plan_required — with the applied limit and the upgrade URL in `details` — when the WORKSPACE OWNER's plan is already at its list limit; the caller's own subscription is irrelevant, because the owner pays for the workspace. The new list is expanded and empty, and every open board of the workspace — the caller's own included — receives it in realtime. The workspace activity feed shows it as `list_created` automatically from the row itself, so no activity entry can be (or needs to be) supplied.

Endpoint	What it does
`POST /lists/:listId/tasks`writecreate_task	Create a task at the end of a list. `text` is the title (1–50000 characters); `taskDescription` is the optional markdown body (max 100000); `date` and `time` are the plain strings the board stores (`"2026-09-10"`, `"14:30"`) — not ISO datetimes. The workspace owner's per-list task limit is enforced and answered with `plan_required` (plus `upgradeUrl`), so a refusal never leaves half a task behind. Requires the editor role or higher in the list's workspace; every open board of the workspace — the caller's own included, so the task appears without a refresh — receives it in realtime (the API never sends push notifications). Use `get_task` on the returned `id` if you need the body back.
`DELETE /tasks/:taskId`writeremoves datadelete_task	Delete a task. The deletion is SOFT: the row is kept with its REAL title (never replaced by a placeholder) and gets a `deletedAt` stamp, so tracked time and the stats views stay intact and readable; the task disappears from `list_tasks`/`get_task`. Any running timer on it is discarded and the remaining tasks of the list are renumbered so the board has no gap. The API exposes no undelete. Requires the editor role or higher.
`GET /tasks/:taskId`readget_task	Fetch one task in full: `text`, `taskDescription` (the markdown body), dates, title color, order, the recurrence fields, `expanded`, `listId`, `workspaceId` and its subtasks (ordered, each with id/text/done/order/createdAt), plus the caller's `permissions.role` in that workspace. Use it after `list_tasks` whenever the body or the subtasks matter — the list rows carry only `hasDescription`. A task that does not exist, a task in a workspace the token's user cannot access, and a task that was soft-deleted (or whose list was) all answer the same 404 `Task not found`, so this endpoint cannot be used to probe for task ids.
`PATCH /tasks/:taskId`writeupdate_task	Update one task; only the fields you send change (a PATCH, never a replace). Position is NOT a field here — reorder with `move_task`, not with `update_task`. Send `taskDescription: null`, `date: null`, `time: null` or `titleColor: null` to clear a field. Setting `done: true` on an open task runs the FULL completion flow: running timers on it are stopped, a `task_completed` entry is added to the workspace feed, and a recurring task spawns its next occurrence as a new task (which counts against the owner's task limit). `text` must be a non-empty title and `done` an explicit boolean. `expanded` is per-user view state: it is stored but neither broadcast nor logged. Requires the editor role or higher.
`POST /tasks/:taskId/complete`writecomplete_task	Mark a task complete — the explicit form of `update_task` with `done: true`, and the tool to prefer when completion is the whole point. Idempotent: completing a task that is already done changes nothing, writes no second feed entry and spawns no duplicate recurrence. Running time trackers on the task are stopped with reason TASK_COMPLETED, a `task_completed` entry is added to the workspace feed, and a recurring task's next occurrence is created (subject to the workspace owner's per-list task limit, `plan_required`). Requires the editor role or higher.
`POST /tasks/:taskId/move`writemove_task	Move a task within its list or into another list of the SAME workspace, anchored on a neighbouring task. Without `targetTaskId` the task goes to the END of `targetListId`; with it, the task is placed before that task, or after it when `insertAfter` is true. The anchor must belong to `targetListId` — an unknown anchor answers 404 rather than silently appending. Both lists are renumbered in a single transaction, so the task is never in neither list; a move into a different list also counts against the workspace owner's per-list task limit (`plan_required`). Open boards are refreshed through a `TASK_UPDATED` socket event. Requires the editor role or higher.
`POST /tasks/:taskId/reopen`writereopen_task	Reopen a completed task (`done: true` → `false`). Idempotent: a task that is already open is returned unchanged and writes no feed entry. Reopening does NOT restore the recurrence fields that completing the task cleared, and it does not touch any occurrence that was already spawned — the occurrence is a separate task. Requires the editor role or higher.
`POST /tasks/:taskId/subtasks`writeadd_subtask	Add a subtask (a plain checklist item, 1–500 characters) to a task; it is appended after the existing subtasks. Subtasks have no body, no dates, no assignee and no soft delete of their own — they belong to the task and vanish with it. The read side of this is `get_task`, which returns the task's subtasks ordered. Requires the editor role or higher.
`GET /workspaces/:id/tasks`readlist_tasks	List the tasks of a workspace, newest first, optionally narrowed to one list and/or by completion, date or last update. Each row is a SUMMARY: it has `id`, `listId`, `text`, `done`, `date`, `time`, `titleColor`, `order`, the recurrence fields, `hasDescription`, `subtaskCount` and timestamps — the markdown body is NOT included, only the `hasDescription` flag, and `text` is truncated at 500 characters. Call `get_task` for a row's full text and body. Filters: `listId` must be a list of this workspace that is not deleted; `done` filters the completion flag; `date` matches the task's date field exactly; `updatedSince` is an ISO-8601 datetime and selects tasks updated after it (scan for changes since your last read). Soft-deleted tasks, and tasks whose list is soft-deleted, are never returned. Paginate with the opaque `cursor` until `nextCursor` is null.

Endpoint	What it does
`DELETE /notes/:noteId`writeremoves datadelete_note	Delete a note permanently (its version history goes with it). Requires the workspace's editor role or higher; a LOCKED note CAN be deleted — the lock protects the content, not the row. A private note is reachable by its author alone, so anybody else (including the workspace owner) gets 404 for it, exactly like a note id that does not exist. A public note's deletion is recorded in the workspace activity feed (a private note's is silent), and the workspace feed rows of a private note are cleared in the same transaction. Returns the deleted id and the title it had. This cannot be undone — read the note first if its content must survive.
`GET /notes/:noteId`readget_note	Read one note in full: the raw title, the derived display title, the complete markdown body, its pin/privacy/lock flags and the caller's role in the note's workspace. Use it after list_notes (or a search hit) when the actual content is needed. A note that does not exist, another author's private note, and a note in a workspace the caller cannot access all answer 404 with the same message, so this route cannot be used to discover notes.
`PATCH /notes/:noteId`writeupdate_note	Update a note: its title, its markdown body, its pin or its privacy flag. Send only the fields to change. PRIVACY IS AUTHOR-ONLY: only the note's author may set `isPrivate` (403 otherwise), and a flip to private deletes the note's existing workspace-feed rows in the same transaction. A LOCKED note rejects title/body writes with 403 (`this note is locked`) for everyone including its author — pin and privacy still work on a locked note; unlock it in the UI first if the content must change. Content edits snapshot the previous state as a restorable version, with the same checkpoint/interval rules as the editor (`checkpoint: true` on the final save of an editing session creates a restore point without the autosave time gate). A note that does not exist, another author's private note and a note in a workspace you cannot access all answer 404, so this route cannot be used to probe note ids. Returns the stored note.
`GET /workspaces/:id/notes`readlist_notes	List the notes of one workspace with their metadata and a short preview. Notes another author marked private are invisible to everyone else (no owner override), and the full markdown body is never part of a list response — call get_note for one note's content. Use it to find a note by browsing: page with `cursor`/`nextCursor`, or filter to pinned notes with `pinned=true`. Requires access to the workspace; an unknown or foreign workspace id answers 404.
`POST /workspaces/:id/notes`writecreate_note	Create a note (a markdown document) in a workspace. Requires the workspace's editor role or higher — the same floor as creating a note in the UI — and the workspace OWNER's plan must allow another note. Titles are optional (the first H1 of the body becomes the display title, otherwise "Untitled"); a note can be pinned, and a private note is readable by its author alone. Use it to capture a document for the team; the workspace feed records a public note's creation (a private note stays silent). A foreign or unknown workspace id answers 404. Returns the stored note, so no follow-up `get_note` is needed.

Endpoint	What it does
`GET /workspaces/:id/lists/:listId/stats`readget_list_time_stats	Read the time-tracking overview of ONE list (same shape as `get_time_stats`, with `scope: "LIST"` and the list echoed in `entity`): totals, streaks, per-user and per-task breakdowns and the running timers for that list. The `listId` comes from the path and must belong to the workspace and not be deleted, otherwise the call answers 404. `from` and `to` are day keys (`YYYY-MM-DD`) in the caller's timezone and the window is inclusive; it defaults to the last 90 days and may span at most 366 days. An omitted window NEVER means all time — all-time statistics are not exposed in v1 — and `window.defaulted` in the response tells you whether the default was applied. Owners and moderators see the whole workspace; viewers and editors only ever see their own tracked time (`visibility: "own"`). Requires time tracking on the workspace owner's plan, otherwise the call answers 403 `plan_required`.
`GET /workspaces/:id/stats/lists`readget_list_stats	List every list of the workspace with its tracked time (total, active, session count, task count) plus workspace totals, sorted by the field you choose. Soft-deleted lists that still carry tracked time are kept with `deleted: true`; deleted lists without time are hidden. Pagination has no total count in the response (unlike `get_task_stats`), so raise `pageSize` (max 200) when you need every list. `from` and `to` are day keys (`YYYY-MM-DD`) in the caller's timezone and the window is inclusive; it defaults to the last 90 days and may span at most 366 days. An omitted window NEVER means all time — all-time statistics are not exposed in v1 — and `window.defaulted` in the response tells you whether the default was applied. Owners and moderators see the whole workspace; viewers and editors only ever see their own tracked time (`visibility: "own"`). Requires time tracking on the workspace owner's plan, otherwise the call answers 403 `plan_required`.
`GET /workspaces/:id/stats/tasks`readget_task_stats	List every task of the workspace with its tracked time (total, active, session count, contributors, last tracked) and pagination metadata, sorted by the field you choose. Soft-deleted tasks are included with their real name and `deleted: true` so the hours stay attributable — do not treat them as live tasks. `from` and `to` are day keys (`YYYY-MM-DD`) in the caller's timezone and the window is inclusive; it defaults to the last 90 days and may span at most 366 days. An omitted window NEVER means all time — all-time statistics are not exposed in v1 — and `window.defaulted` in the response tells you whether the default was applied. Owners and moderators see the whole workspace; viewers and editors only ever see their own tracked time (`visibility: "own"`). Requires time tracking on the workspace owner's plan, otherwise the call answers 403 `plan_required`.
`GET /workspaces/:id/stats/time`readget_time_stats	Read the workspace time-tracking overview for one date window: totals, streaks, daily and heatmap series, per-user and per-task breakdowns, billing (when visible) and the currently running timers. Use it to answer "how much time was tracked where, and by whom". `from` and `to` are day keys (`YYYY-MM-DD`) in the caller's timezone and the window is inclusive; it defaults to the last 90 days and may span at most 366 days. An omitted window NEVER means all time — all-time statistics are not exposed in v1 — and `window.defaulted` in the response tells you whether the default was applied. Owners and moderators see the whole workspace; viewers and editors only ever see their own tracked time (`visibility: "own"`). Requires time tracking on the workspace owner's plan, otherwise the call answers 403 `plan_required`.

Endpoint	What it does
`GET /tracker/active`readget_active_timer	Read the caller's own running time tracker: the task it belongs to (`taskId`, `task.text`), its list and workspace, `startedAt`, how many seconds have elapsed, and whether it is waiting for a confirmation (`requiresConfirmation`) or was manually paused (`isManuallyPaused`). Answers `null` when no timer is running, which is the normal case. Call it before `start_timer` to see what is already running, and after `start_timer`/`stop_timer` to confirm the new state. No parameters: a timer is per user, never per workspace, so a token can only ever see its own. Requires time tracking on the workspace owner's plan only when the caller starts a timer — this read is always available and may end a timer whose confirmation window has expired (the same in-band sync the web app performs), which is why a timer can never get stuck.
`POST /tracker/start`writestart_timer	Start tracking time on a task: it becomes the caller's single running timer and is returned in `activeTimer`. The workspace owner's plan must include time tracking (Premium Plus or Team), otherwise the call answers 403 `plan_required` — a FREE member of such a workspace may still track, and the check is never about the token owner's own tier. Only an open task can be tracked: a completed one answers 409, a task that does not exist, was deleted, sits in a deleted list or lives in a workspace the caller cannot see answers 404 (identically — this endpoint cannot be used to probe for task ids). The caller has exactly ONE timer, so starting a different task is not an error and not a silent loss: the running session is first written as a time entry with `stopReason: "SWITCHED_TASK"` (so the earlier time stays attributed) and then the new timer starts. Starting the task that is already running is a no-op that returns it. Stop it with `stop_timer`.
`POST /tracker/stop`writestop_timer	Stop the caller's running timer and persist it as a time entry: the response is `{ activeTimer: null, timeEntry }` with `startedAt`, `endedAt`, `durationSeconds` and `stopReason` (`MANUAL`; the in-band sync can instead produce `REMINDER_TIMEOUT`, and the app's own switch/complete paths use `SWITCHED_TASK`/`TASK_COMPLETED`). Answers 404 when no timer is running. Pass `taskId` to be safe: if the running timer belongs to a DIFFERENT task the call answers 409 `conflict` instead of stopping a timer the caller did not name; omit `taskId` to stop whatever is running, which is the form that always works. This endpoint is deliberately NOT plan-gated — stopping must keep working after the workspace owner's plan is downgraded, otherwise a timer could never be ended.

Endpoint	What it does
`GET /workspaces/:id/media`readlist_media	List the files stored in one workspace (the Media & Storage view), newest first, together with the workspace total, the workspace owner's account-wide usage, the effective quota and the usage percentage. Use it to see what a workspace stores and how full the owner's plan is; follow nextCursor to walk every file. Requires the EDITOR, MODERATOR or OWNER role — a VIEWER is refused with 403 exactly like the in-app tab, and a workspace the token's user is not a member of answers 404. `url` is the AUTHENTICATED IN-APP path (`/api/media/<storageKey>`) that a signed-in workspace member's browser can open; fetching the bytes with an API token is NOT part of v1 and is deferred to the storage write phase, so treat `url` as a stable reference rather than a downloadable link. totalCount, workspaceSizeBytes, ownerTotalSizeBytes and ownerUsagePercent describe the whole workspace / the owner's whole account and are never derived from the returned page.
`POST /workspaces/:id/media`writemultipart uploadupload_media	Upload one image into a workspace and return the stored file as `list_media` returns it (plus `key`). Send the request as multipart/form-data with the bytes in the `file` part (`id` stays in the path — do not repeat it as a form field). Accepted formats are PNG, JPEG, WebP and GIF, decided by the file's MAGIC BYTES and never by a declared Content-Type or file extension; anything else is a 400, and so is a file that cannot be decoded. The file must be at most 5 MB and is always re-encoded to WebP (quality 85), so the returned sizeBytes is the size of the stored file, not of what you sent. Writing into a workspace consumes the workspace OWNER's plan storage, checked against the owner's total usage across all their workspaces; exceeding it answers 413. Requires the EDITOR, MODERATOR or OWNER role — a VIEWER is refused with 403 exactly like the in-app tab, and a workspace the token's user is not a member of answers 404. `url` is the AUTHENTICATED IN-APP path that a signed-in member's browser can open; it is not a fetchable link for an API token.
`DELETE /workspaces/:id/media/:mediaId`writeremoves datadelete_media	Permanently delete one stored file from a workspace, addressed by its `mediaId` (the `id` of a row returned by `list_media`) — never by a storage key. Requires the MODERATOR or OWNER role: an EDITOR may upload media but not delete it, so an EDITOR is refused with 403, exactly like the in-app Media tab, and a workspace the token's user is not a member of answers 404 rather than confirming that it exists. A mediaId that does not belong to the workspace answers 404. This is irreversible: the file bytes and the workspace's media row are both removed, and the free space returns to the workspace owner's quota. Use `list_media` first to get a valid id, and confirm with the user before deleting.

Endpoint What it does

GET /resolvereadresolve_ref Resolve a single reference into the entity it names and WHERE that entity lives: kind, its name, the workspaceId it belongs to and the listId that contains it. Use it FIRST whenever an id was pasted in without its context — a bare cuid is an opaque 25-character string that says nothing about whether it is a workspace, a list, a task or a note, and every other tool needs to know that before it can be called. It accepts both forms of the same id: the paste-ready taskr_w_, taskr_l_, taskr_t_, taskr_n_ references the app's copy buttons produce, and the bare cuid the API has always published. A prefixed reference is looked up in that ONE kind; a bare cuid is looked up as workspace, then list, then task, then note (ids are cuids, so the order only decides an impossible collision), and the answer's kind is read from the table that actually held the row. The prefix therefore SELECTS the table rather than being decoration: taskr_w_<taskId> answers 404 here even though other tools accept it (they strip any known prefix and ignore its kind), so send the reference the app produced. A prefix never grants access — it only narrows the search. An entity that does not exist, one that is soft-deleted, and one in a workspace the caller does not own or belong to ALL answer the same 404, so this cannot be used to test whether an id exists somewhere else. A note the caller may not see (somebody else's private note) answers that same 404. The name is a label for the caller to recognise the entity by, not a full read: a task's text is bounded (use get_task for the whole thing), and a note's is its display title (stored title, else the first heading, else "Untitled"), never its body.

GET /searchreadsearch Search task titles, task descriptions and note titles/content across every workspace the caller owns or is a member of, or within a single workspace when workspaceId is given. Each hit carries the resource ids plus a snippet around the first match, so a result can be opened with get_task/get_note. Another author's private notes are never returned, and workspace membership is resolved before any resource is queried. The search is bounded and has NO cursor: it returns at most 50 matches per type (default 20, clamped) and sets truncated.tasks / truncated.notes when more matched than were returned — narrow the term instead of paging.

Endpoint	What it does
`GET /resolve`readresolve_ref	Resolve a single reference into the entity it names and WHERE that entity lives: `kind`, its `name`, the `workspaceId` it belongs to and the `listId` that contains it. Use it FIRST whenever an id was pasted in without its context — a bare cuid is an opaque 25-character string that says nothing about whether it is a workspace, a list, a task or a note, and every other tool needs to know that before it can be called. It accepts both forms of the same id: the paste-ready `taskr_w_`, `taskr_l_`, `taskr_t_`, `taskr_n_` references the app's copy buttons produce, and the bare cuid the API has always published. A prefixed reference is looked up in that ONE kind; a bare cuid is looked up as workspace, then list, then task, then note (ids are cuids, so the order only decides an impossible collision), and the answer's `kind` is read from the table that actually held the row. The prefix therefore SELECTS the table rather than being decoration: `taskr_w_<taskId>` answers 404 here even though other tools accept it (they strip any known prefix and ignore its kind), so send the reference the app produced. A prefix never grants access — it only narrows the search. An entity that does not exist, one that is soft-deleted, and one in a workspace the caller does not own or belong to ALL answer the same 404, so this cannot be used to test whether an id exists somewhere else. A note the caller may not see (somebody else's private note) answers that same 404. The `name` is a label for the caller to recognise the entity by, not a full read: a task's text is bounded (use `get_task` for the whole thing), and a note's is its display title (stored title, else the first heading, else "Untitled"), never its body.
`GET /search`readsearch	Search task titles, task descriptions and note titles/content across every workspace the caller owns or is a member of, or within a single workspace when `workspaceId` is given. Each hit carries the resource ids plus a snippet around the first match, so a result can be opened with get_task/get_note. Another author's private notes are never returned, and workspace membership is resolved before any resource is queried. The search is bounded and has NO cursor: it returns at most 50 matches per type (default 20, clamped) and sets `truncated.tasks` / `truncated.notes` when more matched than were returned — narrow the term instead of paging.

Taskr API v1, from a script and from an AI assistant

Before your first call

1. Create a token

2. Your first call

3. What the API can and cannot do

4. Conventions worth knowing before you write code

5. Answers and limits you will run into

6. Handing the same surface to an AI assistant

Every endpoint, generated from the API itself

Account and catalog

Workspaces

Taskr API v1, from a script and from an AI assistant

Before your first call

1. Create a token

2. Your first call

3. What the API can and cannot do

4. Conventions worth knowing before you write code

5. Answers and limits you will run into

6. Handing the same surface to an AI assistant

Every endpoint, generated from the API itself

Account and catalog

Workspaces

Lists

Tasks

Notes

Statistics

Time tracking

Stored files

Search and references