API and agents
Everything the app does goes through the same API. Scripts use a personal token; Claude and other MCP clients connect with a browser sign-in.
API v1 only grows. Once a route or a response field is documented here it is never removed or renamed; a breaking change would be a new /api/v2.
Connect Claude
Run this, then sign in and choose what the agent may do:
claude mcp add --transport http darth-tasks https://mcp.darthtasks.comToken scopes
- read
- Reads everything the token's limit allows. For briefs, dashboards and reports.
- capture
- Adds tasks to the Inbox and nothing else. For shortcuts, forms and mail rules.
- write
- Changes anything inside its limit. With approval on, its changes wait as a change set you apply or reject; one undo reverts a whole set.
Sync API for native apps
What a native app needs to stay in step with the account: one snapshot, then changes, and every write as a command.
Snapshot
On first launch, page through GET /api/v1/sync/snapshot until cursor is null. Keep the returned rev: it is where changes continue from.
GET /api/v1/sync/snapshot?cursor=
{
"rows": [
{
"entity": "task",
"id": "01J…",
"rev": 812,
"row": {
"title": "Call the dentist",
"state": "inbox"
}
}
],
"rev": 812,
"cursor": "task:01J…"
}Changes
Then ask GET /api/v1/sync/changes?since=<rev> (or listen on the /api/v1/sync WebSocket). A deleted row arrives with its deletedAt while it is in Trash. When since is older than the account keeps, the answer is 410 resync_required: take a fresh snapshot.
GET /api/v1/sync/changes?since=812
{
"changes": [
{
"entity": "task",
"id": "01J…",
"rev": 813,
"row": {
"title": "Call the dentist",
"state": "next"
}
},
{
"entity": "task",
"id": "01K…",
"rev": 814,
"row": {
"deletedAt": 1795400000000
}
}
],
"rev": 814,
"more": false
}GET https://darthtasks.com/api/v1/sync
Authorization: Bearer <session token>
{}Commands
Every write is a command with an op_id you generate. Send up to 100 to POST /api/v1/commands; each gets its own result, applied or rejected with a code and the current row. Sending the same op_id again returns the first result, so retrying after a lost connection is safe.
POST /api/v1/commands
{
"commands": [
{
"op_id": "01J…",
"type": "task.create",
"input": {
"title": "Buy milk"
}
}
]
}
{
"results": [
{
"op_id": "01J…",
"status": "applied",
"rev": 14
}
]
}Bearer sessions
A native app signs in with Clerk and sends the Clerk session token as Authorization: Bearer <token>. It is the Owner's session, so app-only routes are open to it; agent tokens (dt_…) are not.
Versions and /meta
Send X-Client: <platform>/<version> on every request. GET /api/v1/meta returns the API version, the schema version and the minimum client version per platform; an app older than its minimum gets 426 with the version to update to.
GET /api/v1/meta
{
"apiVersion": "1",
"schemaVersion": 3,
"minClientVersions": {
"ios": "1.0.0",
"android": "1.0.0",
"macos": "1.0.0"
}
}Additive-only rule
API v1 only grows. A documented route or response field is never removed or renamed; a breaking change would be a new /api/v2. Ignore fields you do not know.
Routes
| Routes | Auth | Token scope |
|---|---|---|
GET /api/v1/metaAPI version, schema version and the minimum client version per platform. ExampleGET /api/v1/meta
{
"apiVersion": "1",
"schemaVersion": 3,
"minClientVersions": {
"ios": "1.0.0",
"android": "1.0.0",
"macos": "1.0.0"
}
} | none | |
GET /api/v1/tasksList tasks. `view` = inbox (default), all or done; `state` filters by list; `availableOn=YYYY-MM-DD` hides tasks whose Start is later. ExampleGET /api/v1/tasks
{
"tasks": [
{
"id": "01J…",
"title": "Buy milk",
"state": "inbox",
"source": "quick_add",
"rev": 12
}
]
} | session or token | read |
POST /api/v1/tasksCreate a task. Send `Idempotency-Key` to make retries safe. A token with approval on gets 202 and a change set. ExamplePOST /api/v1/tasks
{
"title": "Call the bank"
}
{
"task": {
"id": "01J…",
"title": "Call the bank"
},
"rev": 13
} | session or token | capture |
GET /api/v1/tasks/:idOne task. ExampleGET https://darthtasks.com/api/v1/tasks/{id}
Authorization: Bearer dt_…
{
"task": "…"
} | session or token | read |
PATCH /api/v1/tasks/:idChange the named fields of a task. `blockedBy` (M17) replaces the list of tasks that must be done first, across projects; a task blocked by itself or a loop through any chain is 422 (`dependency_self`, `dependency_cycle`). ExamplePATCH https://darthtasks.com/api/v1/tasks/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/tasks/:idMove a task to Trash (kept 30 days). ExampleDELETE https://darthtasks.com/api/v1/tasks/{id}
Authorization: Bearer dt_…
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/tasks/:id/completeComplete a task. ExamplePOST https://darthtasks.com/api/v1/tasks/{id}/complete
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/tasks/:id/reopenReopen a completed task. ExamplePOST https://darthtasks.com/api/v1/tasks/{id}/reopen
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/tasks/:id/restoreRestore a task from Trash. ExamplePOST https://darthtasks.com/api/v1/tasks/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/tasks/:id/moveReorder: `before` and `after` are the neighbour ids after the move. ExamplePOST https://darthtasks.com/api/v1/tasks/{id}/move
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/tasks/:id/skipMove a repeating task to its next occurrence without completing it. ExamplePOST https://darthtasks.com/api/v1/tasks/{id}/skip
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/capture/parsePreview what quick add would save from natural language: title, dates, home, tags, estimate, priority and the tokens with positions. ExamplePOST /api/v1/capture/parse
{
"text": "call dentist tomorrow 9am @phone ~15m"
}
{
"title": "call dentist",
"plannedDate": "2026-11-23",
"plannedTime": "09:00",
"tags": [
"phone"
],
"estimateMin": 15
} | session or token | read |
POST /api/v1/inbox/:id/processOne GTD decision: `decision` = do, next, waiting (needs `person`), schedule (needs `plannedDate`), project (needs `nextAction` or `decideLater`), someday, reference, trash. ExamplePOST https://darthtasks.com/api/v1/inbox/{id}/process
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…"
} | session or token | write |
GET /api/v1/trashItems deleted in the last 30 days, newest first, from every content entity: `entity`, `id`, `deletedAt`, `title` and the `row`. After 30 days they are removed for good. A limited token sees only items inside its limit. ExampleGET https://darthtasks.com/api/v1/trash
Authorization: Bearer dt_…
{
"items": "…"
} | session or token | read |
POST /api/v1/trash/:entity/:id/restorePut a trashed item back (M18: every content entity: task, project, area, heading, tag, block, product, routine, backlog_item, release, key_number, request, bet, list, list_item, milestone, template, perspective, week_outcome, reminder, attachment). `item` carries the entity and the row; `task` is set for a task. ExamplePOST https://darthtasks.com/api/v1/trash/{entity}/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…",
"item": "…"
} | session or token | write |
GET /api/v1/activityEvery change with before and after, newest first. `filter` = all, you, ai, agents, deletions; `projectId` keeps only that project's events (its tasks, headings, lists, milestones, reference and files). ExampleGET https://darthtasks.com/api/v1/activity
Authorization: Bearer dt_…
{
"events": "…",
"titles": "…",
"next": "…"
} | session or token | read |
GET /api/v1/activity/exportDownload the activity log as JSON, one object per event, honouring `filter`. ExampleGET https://darthtasks.com/api/v1/activity/export
Authorization: Bearer dt_…
{} | session or token | read |
POST /api/v1/activity/:seq/undoUndo one change. 409 `conflict` names the fields that changed since; send `force: true` to apply. ExamplePOST https://darthtasks.com/api/v1/activity/{seq}/undo
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…"
} | session or token | write |
POST /api/v1/commandsUp to 100 commands with `op_id`s, applied in order; one result per command. ExamplePOST /api/v1/commands
{
"commands": [
{
"op_id": "01J…",
"type": "task.create",
"input": {
"title": "Buy milk"
}
}
]
}
{
"results": [
{
"op_id": "01J…",
"status": "applied",
"rev": 14
}
]
} | session or token | write |
GET /api/v1/change-setsChange sets waiting for approval (`status=all` for every set). ExampleGET https://darthtasks.com/api/v1/change-sets
Authorization: Bearer <session token>
{
"changeSets": "…"
} | app session | |
POST /api/v1/change-setsPropose several changes; the Owner applies or rejects them. ExamplePOST https://darthtasks.com/api/v1/change-sets
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"changeSet": "…",
"rev": "…",
"result": "…"
} | session or token | write |
POST /api/v1/change-sets/:id/applyApply the selected changes (indexes) in one step. ExamplePOST https://darthtasks.com/api/v1/change-sets/{id}/apply
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…"
} | app session | |
POST /api/v1/change-sets/:id/rejectReject a proposed set; nothing changes. ExamplePOST https://darthtasks.com/api/v1/change-sets/{id}/reject
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…"
} | app session | |
POST /api/v1/change-sets/:id/undoUndo every change of an applied set. ExamplePOST https://darthtasks.com/api/v1/change-sets/{id}/undo
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…"
} | app session | |
GET /api/v1/sync/snapshotThe whole account in pages (`cursor`), with the `rev` to continue from. ExampleGET /api/v1/sync/snapshot?cursor=
{
"rows": [
{
"entity": "task",
"id": "01J…",
"rev": 812,
"row": {
"title": "Call the dentist",
"state": "inbox"
}
}
],
"rev": 812,
"cursor": "task:01J…"
} | app session | |
GET /api/v1/sync/changesRows changed after `since`, in rev order; 410 `resync_required` when `since` is too old. ExampleGET /api/v1/sync/changes?since=812
{
"changes": [
{
"entity": "task",
"id": "01J…",
"rev": 813,
"row": {
"title": "Call the dentist",
"state": "next"
}
},
{
"entity": "task",
"id": "01K…",
"rev": 814,
"row": {
"deletedAt": 1795400000000
}
}
],
"rev": 814,
"more": false
} | app session | |
GET /api/v1/syncWebSocket: live changes in the /sync/changes format. ExampleGET https://darthtasks.com/api/v1/sync
Authorization: Bearer <session token>
{} | app session | |
GET /api/v1/tokensAgent tokens and OAuth grants (never the secret). ExampleGET https://darthtasks.com/api/v1/tokens
Authorization: Bearer <session token>
{
"tokens": "…"
} | app session | |
POST /api/v1/tokensCreate a token; the secret is returned once. ExamplePOST https://darthtasks.com/api/v1/tokens
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"token": "…",
"secret": "…"
} | app session | |
DELETE /api/v1/tokens/:idRevoke a token or grant (effective within a minute). ExampleDELETE https://darthtasks.com/api/v1/tokens/{id}
Authorization: Bearer <session token>
{
"ok": "…"
} | app session | |
POST /api/v1/ai/clarifyAI suggestion for one Inbox item (Pro; Lifetime with its own key). 402 on Free, 429 `fair_use` at the weekly limit. ExamplePOST https://darthtasks.com/api/v1/ai/clarify
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"suggestion": "…",
"fixture": "…"
} | app session | |
POST /api/v1/ai/breakdownThree to five next actions for a project (Pro). ExamplePOST https://darthtasks.com/api/v1/ai/breakdown
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"actions": "…",
"fixture": "…"
} | app session | |
POST /api/v1/ai/splitSplit an email or note into separate items to confirm (Pro). ExamplePOST https://darthtasks.com/api/v1/ai/split
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"items": "…",
"fixture": "…"
} | app session | |
GET /api/v1/ai/usageThis week's AI use against the fair-use limit. ExampleGET https://darthtasks.com/api/v1/ai/usage
Authorization: Bearer <session token>
{
"plan": "…",
"week": "…",
"used": "…",
"limit": "…",
"reviewPreps": "…",
"reviewLimit": "…",
"warning": "…",
"hasOwnKey": "…"
} | app session | |
POST /api/v1/ai/keyLifetime: test and save your own Anthropic key (stored encrypted, never returned). ExamplePOST https://darthtasks.com/api/v1/ai/key
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"ok": "…"
} | app session | |
DELETE /api/v1/ai/keyLifetime: remove your own AI key. ExampleDELETE https://darthtasks.com/api/v1/ai/key
Authorization: Bearer <session token>
{
"ok": "…"
} | app session | |
POST /api/v1/capture/voiceAudio (up to 2 minutes) → transcript and the item(s) to confirm. The audio is not stored. ExamplePOST https://darthtasks.com/api/v1/capture/voice
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"transcript": "…",
"items": "…"
} | app session | |
GET /api/v1/accountYour account: email, name, plan and private capture address. ExampleGET https://darthtasks.com/api/v1/account
Authorization: Bearer <session token>
{
"email": "…",
"name": "…",
"plan": "…",
"emailInAddress": "…"
} | app session | |
POST /api/v1/account/email-in/regenerateNew private capture address; the old one stops working. ExamplePOST https://darthtasks.com/api/v1/account/email-in/regenerate
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"emailInAddress": "…"
} | app session | |
GET /api/v1/emails/:idThe email behind an item. ExampleGET https://darthtasks.com/api/v1/emails/{id}
Authorization: Bearer dt_…
{
"email": "…",
"text": "…",
"hasHtml": "…",
"attachments": "…"
} | session or token | read |
GET /api/v1/settingsThe account's settings (time zone, review day, capacity, theme and accent, advanced switches, first run) and `checklist`: the Today checklist items done (capture, clarify, focus, review). ExampleGET https://darthtasks.com/api/v1/settings
Authorization: Bearer <session token>
{
"settings": "…",
"checklist": "…"
} | app session | |
PATCH /api/v1/settingsChange settings: `tz` (an IANA time zone), `workingWeek` (7 windows, Sunday first, null for a day off), `capacity`, `reviewDay`, `reviewNudge`, `notifications`, `advanced`, `theme` (system, light, dark), `accent` (indigo, teal, orange, violet), `checklist` ({dismissed}), `firstRun` (done, skipped). ExamplePATCH https://darthtasks.com/api/v1/settings
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"settings": "…"
} | app session | |
GET /api/v1/billing/planThe plan as Settings shows it. ExampleGET https://darthtasks.com/api/v1/billing/plan
Authorization: Bearer <session token>
{
"plan": "…",
"trialEndsAt": "…",
"trialUsed": "…",
"managedIn": "…",
"subscription": "…",
"canManage": "…",
"lifetime": "…",
"country": "…"
} | app session | |
GET /api/v1/billing/seatsFounding Lifetime seats left (cached 60 s). ExampleGET https://darthtasks.com/api/v1/billing/seats
{
"seatsLeft": "…",
"open": "…"
} | none | |
POST /api/v1/billing/checkoutStripe Checkout for Pro (month or year) or Founding Lifetime. ExamplePOST https://darthtasks.com/api/v1/billing/checkout
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"url": "…"
} | app session | |
POST /api/v1/billing/portalStripe Customer Portal. ExamplePOST https://darthtasks.com/api/v1/billing/portal
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"url": "…"
} | app session | |
POST /api/v1/billing/cancelCancel at period end. ExamplePOST https://darthtasks.com/api/v1/billing/cancel
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"plan": "…",
"subscription": "…"
} | app session | |
POST /api/v1/billing/resumeUndo a cancel before the period ends. ExamplePOST https://darthtasks.com/api/v1/billing/resume
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"plan": "…",
"subscription": "…"
} | app session | |
POST /api/v1/billing/trialStart the 14-day Pro trial (once). ExamplePOST https://darthtasks.com/api/v1/billing/trial
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"plan": "…",
"trialEndsAt": "…"
} | app session | |
GET /api/v1/areasList areas in order; `offered` holds the four starter areas while there are none. ExampleGET https://darthtasks.com/api/v1/areas
Authorization: Bearer dt_…
{
"areas": "…",
"offered": "…"
} | session or token | read |
GET /api/v1/areas/:idOne area with its projects (with progress) and loose tasks. ExampleGET https://darthtasks.com/api/v1/areas/{id}
Authorization: Bearer dt_…
{
"area": "…",
"projects": "…",
"tasks": "…"
} | session or token | read |
POST /api/v1/areasCreate an area. ExamplePOST https://darthtasks.com/api/v1/areas
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"area": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/areas/:idChange only the named fields of an area. ExamplePATCH https://darthtasks.com/api/v1/areas/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"area": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/areas/:idMove an area to Trash (with what it contains). ExampleDELETE https://darthtasks.com/api/v1/areas/{id}
Authorization: Bearer dt_…
{
"area": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/areas/:id/restoreRestore an area from Trash. ExamplePOST https://darthtasks.com/api/v1/areas/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"area": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/areas/:id/moveReorder an area between two neighbours (`before`, `after`). ExamplePOST https://darthtasks.com/api/v1/areas/{id}/move
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"area": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/projectsList projects with progress; `?areaId=<id>` or `?areaId=none` for unfiled projects. ExampleGET https://darthtasks.com/api/v1/projects
Authorization: Bearer dt_…
{
"projects": "…"
} | session or token | read |
GET /api/v1/projects/:idOne project with notes, links, progress, headings and tasks. ExampleGET https://darthtasks.com/api/v1/projects/{id}
Authorization: Bearer dt_…
{
"project": "…",
"headings": "…",
"tasks": "…"
} | session or token | read |
POST /api/v1/projectsCreate a project. ExamplePOST https://darthtasks.com/api/v1/projects
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"project": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/projects/:idChange only the named fields of a project. ExamplePATCH https://darthtasks.com/api/v1/projects/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"project": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/projects/:idMove a project to Trash (with what it contains). ExampleDELETE https://darthtasks.com/api/v1/projects/{id}
Authorization: Bearer dt_…
{
"project": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/projects/:id/restoreRestore a project from Trash. ExamplePOST https://darthtasks.com/api/v1/projects/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"project": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/projects/:id/moveReorder a project between two neighbours (`before`, `after`). ExamplePOST https://darthtasks.com/api/v1/projects/{id}/move
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"project": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/headingsHeadings of one project (`?projectId=`), in order. ExampleGET https://darthtasks.com/api/v1/headings
Authorization: Bearer dt_…
{
"headings": "…"
} | session or token | read |
POST /api/v1/headingsCreate a heading. ExamplePOST https://darthtasks.com/api/v1/headings
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"heading": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/headings/:idChange only the named fields of a heading. ExamplePATCH https://darthtasks.com/api/v1/headings/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"heading": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/headings/:idMove a heading to Trash (with what it contains). ExampleDELETE https://darthtasks.com/api/v1/headings/{id}
Authorization: Bearer dt_…
{
"heading": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/headings/:id/restoreRestore a heading from Trash. ExamplePOST https://darthtasks.com/api/v1/headings/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"heading": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/headings/:id/moveReorder a heading between two neighbours (`before`, `after`). ExamplePOST https://darthtasks.com/api/v1/headings/{id}/move
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"heading": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/tagsList tags by name. ExampleGET https://darthtasks.com/api/v1/tags
Authorization: Bearer dt_…
{
"tags": "…"
} | session or token | read |
PATCH /api/v1/tags/:idRename a tag or set its kind (person, tool, energy, location). ExamplePATCH https://darthtasks.com/api/v1/tags/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"tag": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/tags/:idDelete a tag; tasks lose it. ExampleDELETE https://darthtasks.com/api/v1/tags/{id}
Authorization: Bearer dt_…
{
"tag": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/tags/:id/restoreRestore a deleted tag. ExamplePOST https://darthtasks.com/api/v1/tags/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"tag": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/views/nextNext actions; repeat `?tag=` to keep tasks that carry every tag given. Advanced filters (M17), each applied only while its switch is on: `maxMinutes` (estimate at most N minutes) and `energy` (an energy tag) under energy and time, `location` (a location tag) under locations. With dependencies on, a task whose blocker is still open is left out. ExampleGET https://darthtasks.com/api/v1/views/next
Authorization: Bearer dt_…
{
"tasks": "…"
} | session or token | read |
GET /api/v1/views/waitingWaiting for, by follow-up date; `followUpDue` marks rows due today or earlier. ExampleGET https://darthtasks.com/api/v1/views/waiting
Authorization: Bearer dt_…
{
"tasks": "…"
} | session or token | read |
GET /api/v1/views/somedaySomeday tasks and someday projects. ExampleGET https://darthtasks.com/api/v1/views/someday
Authorization: Bearer dt_…
{
"tasks": "…",
"projects": "…"
} | session or token | read |
GET /api/v1/views/navSidebar counts (inbox, next, waiting, someday), areas and open projects. ExampleGET https://darthtasks.com/api/v1/views/nav
Authorization: Bearer dt_…
{
"counts": "…",
"areas": "…",
"projects": "…"
} | session or token | read |
GET /api/v1/searchSearch tasks and projects (`?q=`); a task hit carries its project's id and name. ExampleGET https://darthtasks.com/api/v1/search
Authorization: Bearer dt_…
{
"tasks": "…",
"projects": "…"
} | session or token | read |
GET /api/v1/views/todayToday: `focus` (up to 3), `planned`, `due`, `followUps`, `more` (from Next) and today's `blocks`; `routinesDue`, `drifting` (M10) and `pinnedLists` (lists pinned to today, M14). ExampleGET https://darthtasks.com/api/v1/views/today
Authorization: Bearer dt_…
{
"date": "…",
"focus": "…",
"planned": "…",
"due": "…",
"followUps": "…",
"more": "…",
"blocks": "…",
"routinesDue": "…",
"drifting": "…",
"pinnedLists": "…",
"events": "…"
} | session or token | read |
GET /api/v1/views/upcomingThe next 14 days from today, each with the tasks planned (or, with no Planned, due) that day, its calendar `events` and its `pinnedLists` (M14). ExampleGET https://darthtasks.com/api/v1/views/upcoming
Authorization: Bearer dt_…
{
"days": "…"
} | session or token | read |
GET /api/v1/views/logbookCompleted tasks grouped by completion day in the account time zone, newest first; `?q=` searches; `?before=` pages. ExampleGET https://darthtasks.com/api/v1/views/logbook
Authorization: Bearer dt_…
{
"days": "…",
"more": "…"
} | session or token | read |
GET /api/v1/capacityFree, planned and buffer minutes per day for `?from=&to=` (default today); `over` when planned is greater than free. ExampleGET https://darthtasks.com/api/v1/capacity
Authorization: Bearer dt_…
{
"days": "…"
} | session or token | read |
GET /api/v1/blocksTime blocks for `?from=&to=` (default today). ExampleGET https://darthtasks.com/api/v1/blocks
Authorization: Bearer dt_…
{
"blocks": "…"
} | session or token | read |
GET /api/v1/blocks/:idOne time block. ExampleGET https://darthtasks.com/api/v1/blocks/{id}
Authorization: Bearer dt_…
{
"block": "…"
} | session or token | read |
POST /api/v1/blocksPlace a task (or a title) on the day: `date`, `start` (HH:MM), `minutes` (default the task's estimate, or 30). ExamplePOST https://darthtasks.com/api/v1/blocks
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"block": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/blocks/:idMove (`date`, `start`) or resize (`minutes`) a block. ExamplePATCH https://darthtasks.com/api/v1/blocks/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"block": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/blocks/:idRemove a block. ExampleDELETE https://darthtasks.com/api/v1/blocks/{id}
Authorization: Bearer dt_…
{
"block": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/blocks/:id/restoreRestore a removed block. ExamplePOST https://darthtasks.com/api/v1/blocks/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"block": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/tasks/:id/focusMake a task a focus item for today (or `date`); a fourth for one day is 409 `focus_full` with the current `ids` unless `replace` names one. ExamplePOST https://darthtasks.com/api/v1/tasks/{id}/focus
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/tasks/:id/focusClear a task's focus. ExampleDELETE https://darthtasks.com/api/v1/tasks/{id}/focus
Authorization: Bearer dt_…
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/calendarGoogle Calendar status: `connected`, the label, the calendars and the `chosen` ones. ExampleGET https://darthtasks.com/api/v1/calendar
Authorization: Bearer <session token>
{
"connected": "…",
"label": "…",
"calendars": "…",
"chosen": "…"
} | app session | |
GET /api/v1/calendar/connectStart connecting Google Calendar (a redirect to Google's consent page). ExampleGET https://darthtasks.com/api/v1/calendar/connect
Authorization: Bearer <session token>
{} | app session | |
GET /api/v1/calendar/callbackGoogle's OAuth callback; a wrong or missing `state` is 400. ExampleGET https://darthtasks.com/api/v1/calendar/callback
Authorization: Bearer <session token>
{} | app session | |
PATCH /api/v1/calendarChoose which calendars to read (`calendars`: ids). ExamplePATCH https://darthtasks.com/api/v1/calendar
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"chosen": "…"
} | app session | |
DELETE /api/v1/calendarDisconnect: revoke at Google, stop channels, delete tokens and cached events. ExampleDELETE https://darthtasks.com/api/v1/calendar
Authorization: Bearer <session token>
{
"connected": "…"
} | app session | |
POST /api/v1/blocks/suggestSuggest a block for a task (`taskId`, `date`) in free time sized by its estimate; `status` is `suggested` and nothing goes to Google. ExamplePOST https://darthtasks.com/api/v1/blocks/suggest
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"block": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/blocks/:id/placeMake a suggested block real; it is then added to the Darth Tasks calendar. ExamplePOST https://darthtasks.com/api/v1/blocks/{id}/place
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"block": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/productsList products. ExampleGET https://darthtasks.com/api/v1/products
Authorization: Bearer dt_…
{
"products": "…"
} | session or token | read |
GET /api/v1/products/:idA product with its projects (next action, progress), loose tasks, routines, key numbers and tab counts; `product.lastActivityAt` and `product.readOnly` included. ExampleGET https://darthtasks.com/api/v1/products/{id}
Authorization: Bearer dt_…
{
"product": "…",
"projects": "…",
"tasks": "…",
"routines": "…",
"numbers": "…",
"counts": "…"
} | session or token | read |
POST /api/v1/productsCreate a product. On Free a second active product is 402 `product_limit`. ExamplePOST https://darthtasks.com/api/v1/products
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"product": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/products/:idChange a product. A read-only product (Free after a downgrade) is 402 `product_read_only`. ExamplePATCH https://darthtasks.com/api/v1/products/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"product": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/products/:idMove a product to Trash. ExampleDELETE https://darthtasks.com/api/v1/products/{id}
Authorization: Bearer dt_…
{
"product": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/products/:id/restoreRestore a product; on Free with another active product it is 402 `product_limit`. ExamplePOST https://darthtasks.com/api/v1/products/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"product": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/products/:id/routinesThe product's routines. ExampleGET https://darthtasks.com/api/v1/products/{id}/routines
Authorization: Bearer dt_…
{
"routines": "…"
} | session or token | read |
POST /api/v1/products/:id/routinesAdd to the product's routines. ExamplePOST https://darthtasks.com/api/v1/products/{id}/routines
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"routine": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/products/:id/backlogThe product's backlog. ExampleGET https://darthtasks.com/api/v1/products/{id}/backlog
Authorization: Bearer dt_…
{
"items": "…"
} | session or token | read |
POST /api/v1/products/:id/backlogAdd to the product's backlog. ExamplePOST https://darthtasks.com/api/v1/products/{id}/backlog
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/products/:id/releasesThe product's releases. ExampleGET https://darthtasks.com/api/v1/products/{id}/releases
Authorization: Bearer dt_…
{
"releases": "…"
} | session or token | read |
POST /api/v1/products/:id/releasesAdd to the product's releases. ExamplePOST https://darthtasks.com/api/v1/products/{id}/releases
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"release": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/products/:id/numbersThe product's numbers. ExampleGET https://darthtasks.com/api/v1/products/{id}/numbers
Authorization: Bearer dt_…
{
"numbers": "…"
} | session or token | read |
POST /api/v1/products/:id/numbersAdd to the product's numbers. A sixth number is 422. ExamplePOST https://darthtasks.com/api/v1/products/{id}/numbers
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"number": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/areas/:id/routinesAn area's routines (same shape as a product's). ExampleGET https://darthtasks.com/api/v1/areas/{id}/routines
Authorization: Bearer dt_…
{
"routines": "…"
} | session or token | read |
POST /api/v1/areas/:id/routinesAdd a routine to an area. ExamplePOST https://darthtasks.com/api/v1/areas/{id}/routines
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"routine": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/routines/:idChange a routine. ExamplePATCH https://darthtasks.com/api/v1/routines/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"routine": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/routines/:idRemove a routine. ExampleDELETE https://darthtasks.com/api/v1/routines/{id}
Authorization: Bearer dt_…
{
"routine": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/routines/:id/restoreRestore a routine. ExamplePOST https://darthtasks.com/api/v1/routines/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"routine": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/backlog/:idChange a item. ExamplePATCH https://darthtasks.com/api/v1/backlog/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/backlog/:idRemove a item. ExampleDELETE https://darthtasks.com/api/v1/backlog/{id}
Authorization: Bearer dt_…
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/backlog/:id/restoreRestore a item. ExamplePOST https://darthtasks.com/api/v1/backlog/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/backlog/:id/moveMove a backlog card to a column (`column`) and between neighbours (`before`, `after`). ExamplePOST https://darthtasks.com/api/v1/backlog/{id}/move
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/backlog/:id/promotePromote a backlog item to a task or a project (`to`); linked both ways. ExamplePOST https://darthtasks.com/api/v1/backlog/{id}/promote
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"promoted": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/releases/:idChange a release. ExamplePATCH https://darthtasks.com/api/v1/releases/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"release": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/releases/:idRemove a release. ExampleDELETE https://darthtasks.com/api/v1/releases/{id}
Authorization: Bearer dt_…
{
"release": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/releases/:id/restoreRestore a release. ExamplePOST https://darthtasks.com/api/v1/releases/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"release": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/releases/:id/shipMark a release shipped (`shippedAt`). ExamplePOST https://darthtasks.com/api/v1/releases/{id}/ship
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"release": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/numbers/:idChange a number. ExamplePATCH https://darthtasks.com/api/v1/numbers/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"number": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/numbers/:idRemove a number. ExampleDELETE https://darthtasks.com/api/v1/numbers/{id}
Authorization: Bearer dt_…
{
"number": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/products/:id/requestsThe product's requests, most asked first; `writable` is false on Free (earlier requests stay readable). ExampleGET https://darthtasks.com/api/v1/products/{id}/requests
Authorization: Bearer dt_…
{
"requests": "…",
"writable": "…"
} | session or token | read |
POST /api/v1/products/:id/requests/logLog an ask (Pro): the same normalised title raises `count` and adds the source; otherwise a new row. Free → 402 `pro_required`. ExamplePOST https://darthtasks.com/api/v1/products/{id}/requests/log
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"request": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/products/:id/requests/:ridChange status or links (`backlogItemId`, `taskId`); with `mergeInto` merge this request into another. ExamplePATCH https://darthtasks.com/api/v1/products/{id}/requests/{rid}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"request": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/products/:id/requests/:ridMove a request to Trash. ExampleDELETE https://darthtasks.com/api/v1/products/{id}/requests/{rid}
Authorization: Bearer dt_…
{
"request": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/products/:id/healthHealth now: `state` (healthy, drifting, neglected) and `reasons` as sentences; `full` is false on Free (activity and routines only). ExampleGET https://darthtasks.com/api/v1/products/{id}/health
Authorization: Bearer dt_…
{
"product": "…",
"state": "…",
"reasons": "…",
"full": "…",
"routines": "…"
} | session or token | read |
GET /api/v1/reviewsRecent review sessions and the Review entry (next review day, catch-up due, nudge, pending change sets). ExampleGET https://darthtasks.com/api/v1/reviews
Authorization: Bearer dt_…
{
"reviews": "…",
"entry": "…"
} | session or token | read |
GET /api/v1/reviews/entryThe Review entry on its own. ExampleGET https://darthtasks.com/api/v1/reviews/entry
Authorization: Bearer dt_…
{
"nextReviewDay": "…",
"lastReviewAt": "…",
"catchUp": "…",
"nudge": "…",
"doneThisWeek": "…",
"pendingChangeSets": "…"
} | session or token | read |
POST /api/v1/reviews/nudge/dismissDismiss this week's in-app review nudge. ExamplePOST https://darthtasks.com/api/v1/reviews/nudge/dismiss
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"week": "…"
} | session or token | write |
POST /api/v1/reviewsStart a review (`kind`: shutdown, weekly, catch_up), or get the open one for this kind and week. ExamplePOST https://darthtasks.com/api/v1/reviews
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"review": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/reviews/:idA review session with its data: `shutdown` tasks, the weekly `steps` with `minutesLeft`, or the `catchUp` batches. ExampleGET https://darthtasks.com/api/v1/reviews/{id}
Authorization: Bearer dt_…
{
"session": "…",
"shutdown": "…",
"steps": "…",
"minutesLeft": "…",
"autoSkipped": "…",
"catchUp": "…"
} | session or token | read |
PATCH /api/v1/reviews/:idSave `step` and `state`, or `finish: true` (a shutdown with an undecided task is 422 `undecided_items`). ExamplePATCH https://darthtasks.com/api/v1/reviews/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"review": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/reviews/:id/decideA shutdown decision for a task: `tomorrow`, `later` (clears Planned), `drop` or `skip`, with an optional `resumeNote`. ExamplePOST https://darthtasks.com/api/v1/reviews/{id}/decide
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"task": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/reviews/:id/catch-upA catch-up batch as one change set: `moveAll` (Planned today) or `restartRoutines`, with `ids`. ExamplePOST https://darthtasks.com/api/v1/reviews/{id}/catch-up
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"batch": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/projects/:id/reviewedMark a project reviewed (`lastReviewedAt`). ExamplePOST https://darthtasks.com/api/v1/projects/{id}/reviewed
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"project": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/products/:id/reviewedMark a product reviewed (`lastReviewedAt`). ExamplePOST https://darthtasks.com/api/v1/products/{id}/reviewed
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"product": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/weeks/:w/outcomesThe week's outcomes (`:w` is an ISO week like 2026-W47). ExampleGET https://darthtasks.com/api/v1/weeks/{w}/outcomes
Authorization: Bearer dt_…
{
"outcomes": "…"
} | session or token | read |
POST /api/v1/weeks/:w/outcomesAdd a week outcome with an optional `day` and `slot`. ExamplePOST https://darthtasks.com/api/v1/weeks/{w}/outcomes
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"outcome": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/weeks/:w/outcomes/:idChange an outcome (title, day, slot, done). ExamplePATCH https://darthtasks.com/api/v1/weeks/{w}/outcomes/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"outcome": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/weeks/:w/outcomes/:idRemove an outcome. ExampleDELETE https://darthtasks.com/api/v1/weeks/{w}/outcomes/{id}
Authorization: Bearer dt_…
{
"outcome": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/reviews/:id/prepThe weekly review's AI preparation: `status` (none, queued, ready, failed, meter, no_key), the summary and the proposed change set. A token limited to areas or products gets no summary and only its own items. ExampleGET https://darthtasks.com/api/v1/reviews/{id}/prep
Authorization: Bearer dt_…
{
"prep": "…"
} | session or token | read |
POST /api/v1/reviews/:id/prepStart the preparation (Pro and Lifetime; Free is 402). Answers 202 with the current `prep`; a limited token is refused (a preparation covers the whole account). ExamplePOST https://darthtasks.com/api/v1/reviews/{id}/prep
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"prep": "…"
} | session or token | write |
POST /api/v1/projects/:id/make-routineTurn a project with a home into a weekly routine named after it; the project is done and its open tasks stay as loose tasks. One Undo reverses all of it. ExamplePOST https://darthtasks.com/api/v1/projects/{id}/make-routine
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/quarters/:qThe quarter view: `bets`, `segments` (13 ISO weeks with `plannedMin`, `freeMin`, `over`, `overByMin`) and `weekOfQuarter`. `:q` is like 2027-Q1. ExampleGET https://darthtasks.com/api/v1/quarters/{q}
Authorization: Bearer dt_…
{
"quarter": "…",
"range": "…",
"today": "…",
"weekOfQuarter": "…",
"bets": "…",
"segments": "…",
"workingWeek": "…"
} | session or token | read |
GET /api/v1/quarters/:q/betsThe quarter's bets with each project's next action. A token limited to areas or products gets only bets whose project is inside its limit. ExampleGET https://darthtasks.com/api/v1/quarters/{q}/bets
Authorization: Bearer dt_…
{
"bets": "…"
} | session or token | read |
POST /api/v1/quarters/:q/betsMake a project a bet on a `side` (work or personal) with an optional `outcome`. A 4th active bet on a side is 409 `bet_cap` with `details.prompt` and `details.active`; repeat with `resolve` `{action: pause, betId}`, `{action: someday}` or `{action: override}`. ExamplePOST https://darthtasks.com/api/v1/quarters/{q}/bets
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"bet": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/quarters/:q/bets/:idChange a bet's `outcome`, `side` or `status` (active, paused, done). ExamplePATCH https://darthtasks.com/api/v1/quarters/{q}/bets/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"bet": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/quarters/:q/bets/:idRemove a bet. ExampleDELETE https://darthtasks.com/api/v1/quarters/{q}/bets/{id}
Authorization: Bearer dt_…
{
"bet": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/quarters/:q/bets/:id/restoreBring a removed bet back. ExamplePOST https://darthtasks.com/api/v1/quarters/{q}/bets/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"bet": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/importImport from Todoist (project CSV, or a zip of them), Things (JSON in Things' URL-scheme shape) or OmniFocus (CSV export): multipart `source` and `file`, up to 10 MB. 202 with the queued `job`. Everything lands as one change set authored Import; undo it with `POST /api/v1/change-sets/:id/undo`. A limited token gets 403. ExamplePOST https://darthtasks.com/api/v1/import
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"job": "…"
} | session or token | write |
GET /api/v1/import/:idAn import's `status` (queued, running, ready, failed), `summary` (counts and every skipped field), `changeSetId` and `error`. ExampleGET https://darthtasks.com/api/v1/import/{id}
Authorization: Bearer dt_…
{
"job": "…"
} | session or token | read |
POST /api/v1/exportExport everything as a zip: darth-tasks.json (every entity), Markdown by area, product and project, and tasks.csv; attachments are listed with signed links valid 7 days. Works on every plan. A token with limitTo gets 403. ExamplePOST https://darthtasks.com/api/v1/export
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"job": "…"
} | session or token | read |
GET /api/v1/export/:idAn export's `status`, `summary`, `expiresAt` and `expired`. ExampleGET https://darthtasks.com/api/v1/export/{id}
Authorization: Bearer dt_…
{
"job": "…"
} | session or token | read |
GET /api/v1/export/:id/downloadThe export zip, for 7 days after it is ready; then 404. ExampleGET https://darthtasks.com/api/v1/export/{id}/download
Authorization: Bearer dt_…
{} | session or token | read |
GET /api/v1/attachments/:id/signedAn attachment through the signed link in an export (`exp`, `sig`), for a session of the same account, until the link expires. ExampleGET https://darthtasks.com/api/v1/attachments/{id}/signed
Authorization: Bearer <session token>
{} | app session | read |
POST /api/v1/reportReport a problem: `message` and the `screen` it came from go to support. Five an hour. ExamplePOST https://darthtasks.com/api/v1/report
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"sent": "…"
} | app session | write |
DELETE /api/v1/accountDelete the account (body `{"confirm": true}`): the session stops working, tokens are revoked, the subscription is cancelled at once and the data is removed for good after 30 days. Billing records stay 5 years. ExampleDELETE https://darthtasks.com/api/v1/account
Authorization: Bearer <session token>
{
"deleted": "…",
"purgeAt": "…"
} | app session | write |
GET /api/v1/perspectivesSaved perspectives in sidebar order, each with `name`, `query` (filters joined by `match` all or any, `group`, `sort`, `dir`, `includeDone`) and `pinned`. ExampleGET https://darthtasks.com/api/v1/perspectives
Authorization: Bearer dt_…
{
"perspectives": "…"
} | session or token | read |
POST /api/v1/perspectivesSave a perspective: `name`, `query` and optional `pinned`. Filter fields: state, tag, project, area, product, due, planned, estimate, priority, title. A token limited to areas or products cannot change perspectives (403). ExamplePOST https://darthtasks.com/api/v1/perspectives
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"perspective": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/perspectives/:idA perspective and its tasks evaluated now, in `groups` (`key`, `label`, `tasks`), 200 tasks a page; `?offset=` with `nextOffset` pages on. A limited token gets only tasks inside its limit. ExampleGET https://darthtasks.com/api/v1/perspectives/{id}
Authorization: Bearer dt_…
{
"perspective": "…",
"total": "…",
"offset": "…",
"nextOffset": "…",
"groups": "…"
} | session or token | read |
PATCH /api/v1/perspectives/:idChange a perspective's `name`, `query` or `pinned`. ExamplePATCH https://darthtasks.com/api/v1/perspectives/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"perspective": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/perspectives/:id/moveReorder: place the perspective between `before` and `after` (ids or null). ExamplePOST https://darthtasks.com/api/v1/perspectives/{id}/move
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"perspective": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/perspectives/:idRemove a perspective; Undo in Activity brings it back with its pin. ExampleDELETE https://darthtasks.com/api/v1/perspectives/{id}
Authorization: Bearer dt_…
{
"perspective": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/perspectives/:id/restoreBring a removed perspective back. ExamplePOST https://darthtasks.com/api/v1/perspectives/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"perspective": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/perspectives/previewApp-only: evaluate an unsaved `query` for the perspective builder. ExamplePOST https://darthtasks.com/api/v1/perspectives/preview
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"total": "…",
"offset": "…",
"nextOffset": "…",
"groups": "…"
} | app session | read |
GET /api/v1/stats/estimatesEstimate accuracy (actual minutes divided by estimated) from completed tasks that have both: `overall`, by project (`projects`) and by tag (`tags`), each with `ratio`, `count`, `estimateMin` and `actualMin`. A limited token gets only rows inside its limit. ExampleGET https://darthtasks.com/api/v1/stats/estimates
Authorization: Bearer dt_…
{
"overall": "…",
"projects": "…",
"tags": "…"
} | session or token | read |
GET /api/v1/weeks/:w/balanceAttention balance for an ISO week (Pro; Free is 402): per product and area the actual share, the planned share and a word (`below`, `on`, `above`, `none`). Time share when the week has minutes, completion share otherwise. No score or rank. ExampleGET https://darthtasks.com/api/v1/weeks/{w}/balance
Authorization: Bearer dt_…
{
"balance": "…"
} | session or token | read |
GET /api/v1/weeks/:wThe week view: Monday to Sunday with `outcomes`, placed `blocks` (with titles), `workingWeek` and the week's `capacity` (`plannedMin`, `freeMin`, `over`, `overByMin`). ExampleGET https://darthtasks.com/api/v1/weeks/{w}
Authorization: Bearer dt_…
{
"week": "…",
"from": "…",
"to": "…",
"workingWeek": "…",
"outcomes": "…",
"blocks": "…",
"capacity": "…"
} | session or token | read |
GET /api/v1/listsQuick lists (not templates, not archived unless `archived=1`), with `total` and `checked` counts. Filters: `projectId`, `taskId`, `templates=1`. ExampleGET https://darthtasks.com/api/v1/lists
Authorization: Bearer dt_…
{
"lists": "…"
} | session or token | read |
POST /api/v1/listsCreate a list: `title`, optional `projectId` or `taskId`, `pinDate`, `sections`, `items` (in order), or `fromTemplateId` / `fromTemplate` (a template's title) to copy its sections and items unchecked. ExamplePOST https://darthtasks.com/api/v1/lists
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/lists/:idA list and its items in order. ExampleGET https://darthtasks.com/api/v1/lists/{id}
Authorization: Bearer dt_…
{
"list": "…",
"items": "…"
} | session or token | read |
PATCH /api/v1/lists/:idChange a list's `title`, `pinDate`, `projectId`, `taskId` or `sections`. ExamplePATCH https://darthtasks.com/api/v1/lists/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"list": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/lists/:idMove a list to Trash. ExampleDELETE https://darthtasks.com/api/v1/lists/{id}
Authorization: Bearer dt_…
{
"list": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/lists/:id/restoreBring a list back from Trash. ExamplePOST https://darthtasks.com/api/v1/lists/{id}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"list": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/lists/:id/pasteAdd one item per pasted line (`text`), in order, optionally in a `section`. ExamplePOST https://darthtasks.com/api/v1/lists/{id}/paste
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/lists/:id/resetUncheck every item. ExamplePOST https://darthtasks.com/api/v1/lists/{id}/reset
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/lists/:id/templateSave the list as a template (sections and items, unchecked). ExamplePOST https://darthtasks.com/api/v1/lists/{id}/template
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/lists/:id/itemsA list's items in order. ExampleGET https://darthtasks.com/api/v1/lists/{id}/items
Authorization: Bearer dt_…
{
"items": "…"
} | session or token | read |
POST /api/v1/lists/:id/itemsAdd an item: `title`, optional `section`. ExamplePOST https://darthtasks.com/api/v1/lists/{id}/items
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/lists/:id/items/:itemIdChange an item's `title`, `section` or `checked`. A list fully checked is archived 3 days later; unchecking cancels it. ExamplePATCH https://darthtasks.com/api/v1/lists/{id}/items/{itemId}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/lists/:id/items/:itemIdRemove an item. ExampleDELETE https://darthtasks.com/api/v1/lists/{id}/items/{itemId}
Authorization: Bearer dt_…
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/lists/:id/items/:itemId/restoreBring a removed item back. ExamplePOST https://darthtasks.com/api/v1/lists/{id}/items/{itemId}/restore
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"item": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
POST /api/v1/lists/:id/items/:itemId/taskTurn an item into a task (in the list's project, or the Inbox); the item links to it. ExamplePOST https://darthtasks.com/api/v1/lists/{id}/items/{itemId}/task
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/templatesProject templates with counts of headings, tasks and lists. A token limited to areas or products gets none. ExampleGET https://darthtasks.com/api/v1/templates
Authorization: Bearer dt_…
{
"templates": "…"
} | session or token | read |
POST /api/v1/templatesSave a project as a template: its headings, tasks, lists and brief, with dates as offsets from `startDate` (default today). Start one with `POST /api/v1/projects` and `fromTemplateId` plus `startDate`. ExamplePOST https://darthtasks.com/api/v1/templates
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"template": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/templates/:idRename a template. ExamplePATCH https://darthtasks.com/api/v1/templates/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"template": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/templates/:idRemove a template. ExampleDELETE https://darthtasks.com/api/v1/templates/{id}
Authorization: Bearer dt_…
{
"template": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/projects/:id/milestonesThe project's milestones in date order, each with its tasks. ExampleGET https://darthtasks.com/api/v1/projects/{id}/milestones
Authorization: Bearer dt_…
{
"milestones": "…"
} | session or token | read |
POST /api/v1/projects/:id/milestonesAdd a milestone (`name`, optional `date`). Put a task under it with `PATCH /api/v1/tasks/:id` and `milestoneId`. ExamplePOST https://darthtasks.com/api/v1/projects/{id}/milestones
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"milestone": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/projects/:id/milestones/:midChange a milestone's `name` or `date`. ExamplePATCH https://darthtasks.com/api/v1/projects/{id}/milestones/{mid}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"milestone": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/projects/:id/milestones/:midRemove a milestone; its tasks stay in the project. ExampleDELETE https://darthtasks.com/api/v1/projects/{id}/milestones/{mid}
Authorization: Bearer dt_…
{
"milestone": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/projects/:id/tabsWhich workspace tabs the project has earned: `lists`, `milestones`, `reference`. ExampleGET https://darthtasks.com/api/v1/projects/{id}/tabs
Authorization: Bearer dt_…
{
"tabs": "…"
} | session or token | read |
GET /api/v1/projects/:id/referenceThe project's reference page: one Markdown `brief`, `links` with titles and `files`. ExampleGET https://darthtasks.com/api/v1/projects/{id}/reference
Authorization: Bearer dt_…
{
"reference": "…"
} | session or token | read |
PUT /api/v1/projects/:id/referenceSet the reference page's `brief` (Markdown text, shown escaped) and `links`. ExamplePUT https://darthtasks.com/api/v1/projects/{id}/reference
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"reference": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/products/:id/referenceThe product's reference page (same shape as a project's). ExampleGET https://darthtasks.com/api/v1/products/{id}/reference
Authorization: Bearer dt_…
{
"reference": "…"
} | session or token | read |
PUT /api/v1/products/:id/referenceSet the product's reference page. ExamplePUT https://darthtasks.com/api/v1/products/{id}/reference
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"reference": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/attachmentsFiles on a parent: `parentType` (task, project, product) and `parentId`. ExampleGET https://darthtasks.com/api/v1/attachments
Authorization: Bearer dt_…
{
"attachments": "…"
} | session or token | read |
POST /api/v1/attachmentsUpload a file as the raw request body with `Content-Type` and `Content-Length`, and `parentType`, `parentId`, `fileName` in the query. Up to 25 MB (413 above), allowed types only (415 otherwise). ExamplePOST https://darthtasks.com/api/v1/attachments
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"attachment": "…",
"rev": "…"
} | session or token | write |
GET /api/v1/attachments/:idThe file itself. Images and PDF are shown inline (`download=1` forces a download); other types always download; `X-Content-Type-Options: nosniff`. ExampleGET https://darthtasks.com/api/v1/attachments/{id}
Authorization: Bearer dt_…
{
"(file)": "…"
} | session or token | read |
DELETE /api/v1/attachments/:idRemove a file; it is gone for everyone, its owner included. ExampleDELETE https://darthtasks.com/api/v1/attachments/{id}
Authorization: Bearer dt_…
{
"attachment": "…",
"rev": "…"
} | session or token | write |
GET /api/v1/remindersReminders, newest first: `kind` (task, review_nudge, change_set), `fireAt`, `channel` (push, email), `status` (pending, sent, failed, blocked) and `error` in words. A token limited to areas or products gets only task reminders inside its limit. ExampleGET https://darthtasks.com/api/v1/reminders
Authorization: Bearer dt_…
{
"reminders": "…"
} | session or token | read |
GET /api/v1/reminders/logThe delivery log: every reminder that fired, with its status and the reason when it failed or was blocked. ExampleGET https://darthtasks.com/api/v1/reminders/log
Authorization: Bearer dt_…
{
"reminders": "…"
} | session or token | read |
GET /api/v1/reminders/:idOne reminder. ExampleGET https://darthtasks.com/api/v1/reminders/{id}
Authorization: Bearer dt_…
{
"reminder": "…"
} | session or token | read |
POST /api/v1/remindersRemind about a task: `taskId`, `fireAt` (epoch ms) and `channel` (push or email). Push goes first; with email also on, a failed or blocked push falls back to email, logged as its own row. ExamplePOST https://darthtasks.com/api/v1/reminders
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"reminder": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/reminders/:idMove a pending reminder (`fireAt`) or change its `channel`. ExamplePATCH https://darthtasks.com/api/v1/reminders/{id}
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"reminder": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
DELETE /api/v1/reminders/:idCancel a reminder. ExampleDELETE https://darthtasks.com/api/v1/reminders/{id}
Authorization: Bearer dt_…
{
"reminder": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/tasks/:id/focus-sessionThe task's open focus session (or null) and its total focus minutes. ExampleGET https://darthtasks.com/api/v1/tasks/{id}/focus-session
Authorization: Bearer dt_…
{
"open": "…",
"focusMinutes": "…"
} | session or token | read |
POST /api/v1/tasks/:id/focus-sessionStart a focus session on the task (one at a time; a session left open elsewhere ends at the last time it was seen). ExamplePOST https://darthtasks.com/api/v1/tasks/{id}/focus-session
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"session": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
PATCH /api/v1/tasks/:id/focus-session`action`: `pause` (with an optional `resumeNote`, saved to the task), `resume`, `stop` or `heartbeat`. Ending a session adds its minutes to the task's actual time. ExamplePATCH https://darthtasks.com/api/v1/tasks/{id}/focus-session
Authorization: Bearer dt_…
Content-Type: application/json
{ … }
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | session or token | write |
GET /api/v1/tasks/:id/estimate-hintThe task's estimate and actual, and `hint` (`ratio`, `count`): actual ÷ estimate over 5 or more finished tasks in the same project or sharing a tag, else null. ExampleGET https://darthtasks.com/api/v1/tasks/{id}/estimate-hint
Authorization: Bearer dt_…
{
"estimateMin": "…",
"actualMin": "…",
"hint": "…"
} | session or token | read |
GET /api/v1/devicesThe account's push targets (label, platform, last seen) and the `vapidPublicKey` a browser subscribes with; a device's keys are never returned. App-only. ExampleGET https://darthtasks.com/api/v1/devices
Authorization: Bearer <session token>
{
"devices": "…",
"vapidPublicKey": "…"
} | app session | read |
POST /api/v1/devicesRegister this browser (or, later, a native app) for push: `kind` (webpush, apns, fcm), `address`, `keys` for webpush, `platform`, `label`. The same address again refreshes `lastSeenAt`. A webpush address must be https on a known push service (422 otherwise). App-only. ExamplePOST https://darthtasks.com/api/v1/devices
Authorization: Bearer <session token>
Content-Type: application/json
{ … }
{
"device": "…",
"rev": "…"
} | app session | write |
DELETE /api/v1/devicesRemove a push target by `address` or `id`. App-only. ExampleDELETE https://darthtasks.com/api/v1/devices
Authorization: Bearer <session token>
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | app session | write |
DELETE /api/v1/devices/:idRemove a push target. App-only. ExampleDELETE https://darthtasks.com/api/v1/devices/{id}
Authorization: Bearer <session token>
{
"result": "…",
"rev": "…",
"changeSet": "…"
} | app session | write |
Also available: GET /api/health, POST /webhooks/clerk, POST /webhooks/stripe, /mcp and https://mcp.darthtasks.com, /oauth/*
Capture from iPhone with a Shortcut
- In Darth Tasks, Settings › Agents: create a token with scope Capture. Copy it once.
- In the Shortcuts app, make a shortcut that receives Text and URLs from the Share Sheet.
- Add the action Get Contents of URL, method POST, to the address below, with the headers and JSON body shown.
- Share any page or text to the shortcut: it lands in your Inbox.
POST https://darthtasks.com/api/v1/tasks
Authorization: Bearer dt_…your capture token…
Content-Type: application/json
{ "title": "Shortcut Input", "links": [{ "url": "https://example.com/a" }] }App-only by design
These stay in the app and are not offered to tokens:
- Billing and plan changes
- Account and settings changes
- Token and agent management
- Calendar connection
- AI suggestions and the AI key
- Voice upload
- Device registration for notifications
- Live sync
- Report a problem
- Account deletion