> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doers.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> A token, four requests, and your script is talking to your workspace.

<Steps>
  <Step title="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:

    ```text theme={null}
    pc_4f1c9b2e8a7d4e5f9c0b1a2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f
    ```

    <Warning>
      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.
    </Warning>

    ```bash theme={null}
    export DOERS_TOKEN="pc_…"
    export DOERS_API="https://api.doers.sh/v2"
    ```
  </Step>

  <Step title="Read your context">
    Start here. One request returns your counters and your highest-scoring open tasks, each with the
    reasons behind its score.

    ```bash theme={null}
    curl "$DOERS_API/context" \
      -H "Authorization: Bearer $DOERS_TOKEN" \
      -H "X-Doers-Today: 2026-09-22"
    ```

    ```json theme={null}
    {
      "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](/concepts/prioritisation).
  </Step>

  <Step title="Add a task from a sentence">
    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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](/concepts/natural-language) for what it understands and what it drops. To set
    fields one by one, including a `deadline`, use `POST /v2/tasks`:

    ```bash theme={null}
    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 }'
    ```
  </Step>

  <Step title="Tick tasks, several at once">
    ```bash theme={null}
    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"] }'
    ```

    ```json theme={null}
    { "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.
  </Step>

  <Step title="Give the same workspace to your assistant">
    The same token opens the MCP server:

    ```bash theme={null}
    claude mcp add --transport http doers https://app.doers.sh/mcp \
      --header "Authorization: Bearer $DOERS_TOKEN"
    ```

    [Connecting a client](/mcp/connecting) covers Claude Desktop, claude.ai, ChatGPT, Cursor, VS Code
    and signing in with OAuth instead of a token.
  </Step>
</Steps>

## 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:

```bash theme={null}
# 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.

<CardGroup cols={2}>
  <Card title="Data model" icon="sitemap" href="/concepts/data-model">
    `when` and `deadline`, project or area, repeat rules, calendar blocks.
  </Card>

  <Card title="Tool reference" icon="wrench" href="/mcp/reference/tasks">
    Every operation with its input, output, REST route and an example.
  </Card>
</CardGroup>