Quickstart

Create a token

In the app, open Settings > API & MCP and create a token. Name it after what will use it (“n8n”, “backup script”) so you can revoke it on its own later. It is shown once and looks like this:

pc_4f1c9b2e8a7d4e5f9c0b1a2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f

A token has no scope and no expiry: it can read and change everything your account can, including creating more tokens. Keep it in an environment variable or a secret store, never in a repository.

export DOERS_TOKEN="pc_…"
export DOERS_API="https://api.doers.sh/v2"

Read your context

Start here. One request returns your counters and your highest-scoring open tasks, each with the reasons behind its score.

curl "$DOERS_API/context" \
  -H "Authorization: Bearer $DOERS_TOKEN" \
  -H "X-Doers-Today: 2026-09-22"

{
  "day": "2026-09-22",
  "counts": { "open": 23, "overdue": 1, "dueToday": 2, "doneLast7Days": 11 },
  "topPriorities": [
    {
      "id": "0ebb429f-a86d-481c-8630-fac53db1c91c",
      "title": "Send the Acme renewal quote",
      "score": 152,
      "reasons": ["2 days overdue", "Priority P3"],
      "when": { "kind": "anytime" },
      "deadline": "2026-09-20",
      "project": "Acme renewal"
    },
    {
      "id": "6da624db-a523-4ba1-8390-1c904a78ea41",
      "title": "Book the Acme kickoff room",
      "score": 100,
      "reasons": ["Due today", "Priority P2"],
      "when": { "kind": "date", "date": "2026-09-22", "hasTime": false, "time": null },
      "deadline": null,
      "project": null
    }
  ],
  "projects": [
    { "id": "244210e4-8437-4655-8980-a70249a99369", "name": "Acme renewal", "openTaskCount": 6 }
  ],
  "areas": [{ "id": "4a91ee5f-0106-42b3-8c11-c168352f0abf", "name": "Clients" }]
}

How the score is computed is on Prioritisation.

Add a task from a sentence

curl -X POST "$DOERS_API/tasks/quick" \
  -H "Authorization: Bearer $DOERS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "raw": "!!! call the Acme accountant #Acme tomorrow 10am" }'

The parser reads !!! as priority 3, #Acme as the project whose name starts with “Acme”, and “tomorrow 10am” as the schedule. It answers with the task and with what it understood:

{
  "task": {
    "id": "1f58b914-5b24-4108-87ac-38887338b3ea",
    "title": "call the Acme accountant",
    "priority": 3,
    "when": { "kind": "date", "date": "2026-09-23", "hasTime": true, "time": "10:00" },
    "projectId": "244210e4-8437-4655-8980-a70249a99369",
    "…": "…"
  },
  "parsed": {
    "title": "call the Acme accountant",
    "priority": 3,
    "projectId": "244210e4-8437-4655-8980-a70249a99369",
    "areaId": null
  }
}

The sentence is read against the server’s clock, which runs in UTC: see Natural language for what it understands and what it drops. To set fields one by one, including a deadline, use POST /v2/tasks:

curl -X POST "$DOERS_API/tasks" \
  -H "Authorization: Bearer $DOERS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Review the Acme contract", "when": "2026-09-24", "time": "14:00", "deadline": "2026-09-30", "priority": 2 }'

Tick tasks, several at once

curl -X POST "$DOERS_API/tasks/complete" \
  -H "Authorization: Bearer $DOERS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c", "6da624db-a523-4ba1-8390-1c904a78ea41"] }'

{ "count": 2, "done": true }

The batch is all or nothing: if you cannot edit one of the tasks, the request fails and none is ticked. "done": false reopens them. Ticking a repeating task creates its next occurrence.

Give the same workspace to your assistant

The same token opens the MCP server:

claude mcp add --transport http doers https://app.doers.sh/mcp \
  --header "Authorization: Bearer $DOERS_TOKEN"

Connecting a client covers Claude Desktop, claude.ai, ChatGPT, Cursor, VS Code and signing in with OAuth instead of a token.

Your day, not the server’s

The server works in UTC and does not know your time zone. Two ways to tell it which day it is for you:

# A header, for the whole request
curl "$DOERS_API/plan" -H "Authorization: Bearer $DOERS_TOKEN" -H "X-Doers-Today: 2026-09-22"

# Or the `day` argument, where an operation takes one
curl "$DOERS_API/plan?day=2026-09-22" -H "Authorization: Bearer $DOERS_TOKEN"

Without either, “today” is the current UTC day. The older header name X-PC-Today is still accepted.

Data model

when and deadline, project or area, repeat rules, calendar blocks.

Tool reference

Every operation with its input, output, REST route and an example.

Get started

Concepts

Your day, not the server’s

Data model

Tool reference

​Your day, not the server’s

Data model

Tool reference

Your day, not the server’s