> ## 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.
# Context and search
> The prioritised context, search, identity, statistics and activity.
7 tools. Each one is also a REST route and a CLI command, from the same definition: the same input, the same output, the same errors.
| Tool | What it does | Kind |
| ----------------------------------------------- | ---------------------------------------- | -------------------------------------- |
| [`get_context`](#get_context) | Get the prioritised workspace context | Read · idempotent · no outside service |
| [`get_stats`](#get_stats) | Read the raw activity events | Read · idempotent · no outside service |
| [`list_activity`](#list_activity) | The feed | Read · idempotent · no outside service |
| [`list_realtime_events`](#list_realtime_events) | List realtime events since a cursor | Read · idempotent · no outside service |
| [`search`](#search) | Search the workspace | Read · idempotent · no outside service |
| [`whoami`](#whoami) | Identify the account and the server date | Read · idempotent · no outside service |
| [`send_flame`](#send_flame) | Send a flame | Write · no outside service |
## get\_context
**Get the prioritised workspace context.**
The entry point to call **first**. Returns, in one call: the workspace counters, the tasks scored highest by the prioritisation engine (with the reasons behind each score), the active projects and the areas.
The score combines the deadline, the scheduled date, the priority and whether the task belongs to a project. Calendar blocks are excluded.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Read · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `GET https://api.doers.sh/v2/context` |
| CLI | `doers context get` |
| Touches | `areas`, `projects`, `tasks`, `user` |
| Operation | `getContext` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| --------------- | ------- | -------- | ------- | -------------- | ----------------------------------------------------------------- |
| `limit` (query) | integer | no | `15` | 1 to 50 | *No description in the registry.* |
| `day` (query) | string | no | | `YYYY-MM-DD` | Reference day in YOUR timezone. Defaults to the server's UTC day. |
### Output
| Field | Type | Allowed values | Description |
| ------------------------------ | ------------------------- | ------------------------------------- | --------------------------------------------------------- |
| `day` | string | | |
| `counts` | object | | |
| `counts.open` | integer | -9007199254740991 to 9007199254740991 | |
| `counts.overdue` | integer | -9007199254740991 to 9007199254740991 | |
| `counts.dueToday` | integer | -9007199254740991 to 9007199254740991 | |
| `counts.doneLast7Days` | integer | -9007199254740991 to 9007199254740991 | |
| `topPriorities` | object\[] | | |
| `topPriorities[].id` | string | | |
| `topPriorities[].title` | string | | |
| `topPriorities[].score` | number | | |
| `topPriorities[].reasons` | string\[] | | |
| `topPriorities[].when` | object | | How the task is scheduled (distinct from its `deadline`). |
| `topPriorities[].when.kind` | string | `today`, `anytime`, `someday`, `date` | |
| `topPriorities[].when.date` | string (optional) | | |
| `topPriorities[].when.hasTime` | boolean (optional) | | |
| `topPriorities[].when.time` | string \| null (optional) | | |
| `topPriorities[].deadline` | string \| null | | |
| `topPriorities[].project` | string \| null | | |
| `projects` | object\[] | | |
| `projects[].id` | string | | |
| `projects[].name` | string | | |
| `projects[].openTaskCount` | integer | -9007199254740991 to 9007199254740991 | |
| `areas` | object\[] | | |
| `areas[].id` | string | | |
| `areas[].name` | string | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_context",
"arguments": {
"limit": 15,
"day": "2026-09-22"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "3 open task(s), 3 overdue, 3 due today.\nPriorities:\n- [bd3d1324-95a8-4d65-8637-2d8f94e5c165] Prepare the Acme quarterly review · Notes for the Acme launch."
}
],
"structuredContent": {
"day": "2026-09-22",
"counts": {
"open": 3,
"overdue": 3,
"dueToday": 3,
"doneLast7Days": 3
},
"topPriorities": [
{
"id": "bd3d1324-95a8-4d65-8637-2d8f94e5c165",
"title": "Prepare the Acme quarterly review",
"score": 3,
"reasons": ["Notes for the Acme launch."],
"when": {
"kind": "today"
},
"deadline": "2026-09-22",
"project": "Notes for the Acme launch."
}
],
"projects": [
{
"id": "244210e4-8437-4655-8980-a70249a99369",
"name": "Acme",
"openTaskCount": 3
}
],
"areas": [
{
"id": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
"name": "Acme"
}
]
}
}
}
```
```bash CLI theme={null}
doers context get --limit 15 --day 2026-09-22
```
## get\_stats
**Read the raw activity events.**
Completions and sessions since `since`, plus every day plan, all unaggregated. Bucketing by day or hour happens in the caller's timezone, so the server returns moments rather than buckets: an hour histogram computed here would be wrong for everyone outside UTC. Plans are keyed by local day, which `since` cannot be compared against without that same timezone, so they are not windowed.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Read · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `GET https://api.doers.sh/v2/stats` |
| CLI | `doers stats get` |
| Touches | `coachPlanTasks`, `coachPlans` |
| Operation | `getStats` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| --------------- | ------ | -------- | ------- | -------------- | ------------------- |
| `since` (query) | number | yes | | | Epoch milliseconds. |
### Output
| Field | Type | Allowed values | Description |
| --------------------------- | -------------- | --------------------------------- | --------------------------------------------------------------------------------- |
| `completions` | object\[] | | |
| `completions[].id` | string | | |
| `completions[].title` | string | | |
| `completions[].completedAt` | number | | Epoch milliseconds. |
| `completions[].projectId` | string \| null | | |
| `completions[].areaId` | string \| null | | |
| `sessions` | object\[] | | |
| `sessions[].id` | string | | |
| `sessions[].taskId` | string \| null | | |
| `sessions[].title` | string | | |
| `sessions[].startedAt` | number | | Epoch milliseconds. |
| `sessions[].endedAt` | number \| null | | `null` while the session is still running. |
| `sessions[].visibility` | string | `public`, `anonymized`, `private` | What the activity feed may show of it. Private until shared at the session's end. |
| `plans` | object\[] | | |
| `plans[].day` | string | `YYYY-MM-DD` | Local day key, `YYYY-MM-DD`. |
| `plans[].taskIds` | string\[] | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_stats",
"arguments": {
"since": 3
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "1 completed · 1 session(s) · 1 plan(s)."
}
],
"structuredContent": {
"completions": [
{
"id": "21606b58-37ee-4917-8e56-cff2afe21083",
"title": "Prepare the Acme quarterly review",
"completedAt": 1790069400000,
"projectId": "244210e4-8437-4655-8980-a70249a99369",
"areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
}
],
"sessions": [
{
"id": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb",
"taskId": "0ebb429f-a86d-481c-8630-fac53db1c91c",
"title": "Prepare the Acme quarterly review",
"startedAt": 1790069400000,
"endedAt": 1790069400000,
"visibility": "public"
}
],
"plans": [
{
"day": "2026-09-22",
"taskIds": ["0ebb429f-a86d-481c-8630-fac53db1c91c"]
}
]
}
}
}
```
```bash CLI theme={null}
doers stats get --since 3
```
## list\_activity
**The feed.**
Finished sessions shared by the people you follow, and your own, newest first. A public one names the task; an anonymized one names only where it lived; a private one is not here.
| | |
| --------- | -------------------------------------------------------------------------------- |
| Kind | Read · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `GET https://api.doers.sh/v2/activity` |
| CLI | `doers activity list` |
| Touches | `areas`, `follows`, `projects`, `sessionFlames`, `tasks`, `user`, `workSessions` |
| Operation | `listActivity` |
### Input
This tool takes no arguments.
### Output
| Field | Type | Allowed values | Description |
| ---------------------------- | -------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items` | object\[] | | |
| `items[].session` | object | | |
| `items[].session.id` | string | | |
| `items[].session.startedAt` | number | | Epoch milliseconds. |
| `items[].session.endedAt` | number | | Epoch milliseconds. |
| `items[].session.visibility` | string | `public`, `anonymized`, `private` | Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private. |
| `items[].person` | object | | |
| `items[].person.username` | string | | |
| `items[].person.name` | string | | |
| `items[].person.image` | string \| null | | |
| `items[].minutes` | integer | 0 to 9007199254740991 | |
| `items[].title` | string \| null | | The task's title; the owner always sees it; a follower only when the session is public. |
| `items[].container` | string \| null | | The project or area the task lived in, whatever the visibility. |
| `items[].flames` | integer | 0 to 9007199254740991 | |
| `items[].flamed` | boolean | | Whether the caller sent one. |
| `items[].isMe` | boolean | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_activity",
"arguments": {}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "- @ada · 30 min on Prepare the Acme quarterly review · 🔥 3"
}
],
"structuredContent": {
"items": [
{
"session": {
"id": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb",
"startedAt": 1790069400000,
"endedAt": 1790069400000,
"visibility": "public"
},
"person": {
"username": "ada",
"name": "Acme",
"image": "https://acme.example/ada.png"
},
"minutes": 30,
"title": "Prepare the Acme quarterly review",
"container": "Notes for the Acme launch.",
"flames": 3,
"flamed": true,
"isMe": true
}
]
}
}
}
```
```bash CLI theme={null}
doers activity list
```
## list\_realtime\_events
**List realtime events since a cursor.**
Returns this account's events on the one realtime log, oldest first, after `since`. That id is the resume token: reconnect with it to fill a gap. An omitted `since` starts from the oldest retained event. A `channel` narrows to one stream (inbox, a place, a run, or activity). This read does not mark anything read.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Read · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `GET https://api.doers.sh/v2/realtime/events` |
| CLI | `doers realtime list-realtime-events` |
| Touches | `realtimeEvents` |
| Operation | `listRealtimeEvents` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| ----------------- | ------- | -------- | ------- | ------------------- | -------------------------------------------------------------- |
| `since` (query) | string | no | | UUID | Last event id already received. Omit to start from the oldest. |
| `channel` (query) | string | no | | 1 to 120 characters | One stream. Omit to read every channel for this account. |
| `limit` (query) | integer | no | `50` | 1 to 200 | How many events to return. |
### Output
| Field | Type | Allowed values | Description |
| -------------------- | -------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `events` | object\[] | | |
| `events[].id` | string | | |
| `events[].channel` | string | | |
| `events[].kind` | string | `message`, `needs-approval`, `share-invite`, `coach-brief`, `run-status`, `read` | |
| `events[].title` | string | | |
| `events[].body` | string \| null | | |
| `events[].deepLink` | string | | |
| `events[].createdAt` | number | | Epoch milliseconds. |
| `cursor` | string \| null | UUID | Id of the last event in this page, or null when empty. |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_realtime_events",
"arguments": {
"since": "6b5a3ded-016a-4782-8989-8c6e38d09f71",
"channel": "Notes for the Acme launch."
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "1 event(s), cursor 46a4eebd-20d8-41ec-8c0e-cb54f6d83465."
}
],
"structuredContent": {
"events": [
{
"id": "b8e1f80b-d70a-4078-8c78-55a451731b74",
"channel": "Notes for the Acme launch.",
"kind": "message",
"title": "Prepare the Acme quarterly review",
"body": "Notes for the Acme launch.",
"deepLink": "https://acme.example/brief",
"createdAt": 1790069400000
}
],
"cursor": "46a4eebd-20d8-41ec-8c0e-cb54f6d83465"
}
}
}
```
```bash CLI theme={null}
doers realtime list-realtime-events --since 6b5a3ded-016a-4782-8989-8c6e38d09f71 --channel "Notes for the Acme launch."
```
## search
**Search the workspace.**
Text search across task titles, project names and area names. Use this **before** asking the user for an identifier.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Read · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `GET https://api.doers.sh/v2/search` |
| CLI | `doers context search` |
| Touches | `areas`, `projects`, `tasks`, `user` |
| Operation | `search` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| --------------- | --------- | -------- | ------- | ------------------------------- | ------------------------------------------- |
| `query` (query) | string | yes | | 2 to 200 characters | *No description in the registry.* |
| `kinds` (query) | string\[] | no | | each: `task`, `project`, `area` | Restrict the search. Defaults to all three. |
| `limit` (query) | integer | no | `20` | 1 to 50 | *No description in the registry.* |
### Output
| Field | Type | Allowed values | Description |
| ------------------ | -------------- | ------------------------- | ----------- |
| `results` | object\[] | | |
| `results[].kind` | string | `task`, `project`, `area` | |
| `results[].id` | string | | |
| `results[].label` | string | | |
| `results[].detail` | string \| null | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "search",
"arguments": {
"query": "Acme",
"limit": 20
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "- [f6a214f7-a5fc-4a0c-8cee-9660b7fc29f5] (task) Acme"
}
],
"structuredContent": {
"results": [
{
"kind": "task",
"id": "f6a214f7-a5fc-4a0c-8cee-9660b7fc29f5",
"label": "Acme",
"detail": "Notes for the Acme launch."
}
]
}
}
}
```
```bash CLI theme={null}
doers context search Acme --limit 20
```
## whoami
**Identify the account and the server date.**
Returns the token holder's profile and the workspace counters.
`nextUsernameChangeAt` is `null` when the username can be changed now, and a moment otherwise: a username is a public URL, so it moves at most once a fortnight.
**Important about dates**: the server does not know your timezone and reasons in UTC. `serverDay` is the current UTC day. If your timezone differs, pass `day` explicitly to the operations that accept it.
| | |
| --------- | ------------------------------------------------------------------------------- |
| Kind | Read · idempotent · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `GET https://api.doers.sh/v2/me` |
| CLI | `doers context whoami` |
| Touches | `areas`, `projects`, `tasks`, `user` |
| Operation | `whoami` |
### Input
This tool takes no arguments.
### Output
| Field | Type | Allowed values | Description |
| ---------------------- | -------------- | ------------------------------------- | ----------- |
| `userId` | string | | |
| `name` | string \| null | | |
| `email` | string \| null | | |
| `username` | string \| null | | |
| `image` | string \| null | | |
| `usernameUpdatedAt` | number \| null | | |
| `nextUsernameChangeAt` | number \| null | | |
| `serverDay` | string | | |
| `serverTime` | number | | |
| `counts` | object | | |
| `counts.openTasks` | integer | -9007199254740991 to 9007199254740991 | |
| `counts.projects` | integer | -9007199254740991 to 9007199254740991 | |
| `counts.areas` | integer | -9007199254740991 to 9007199254740991 | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "whoami",
"arguments": {}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Account ada · 3 open task(s) · server day 2026-09-22."
}
],
"structuredContent": {
"userId": "04f8996d-a763-47a9-89b1-028ee3007569",
"name": "Acme",
"email": "ada@acme.example",
"username": "ada",
"image": "https://acme.example/ada.png",
"usernameUpdatedAt": 1790069400000,
"nextUsernameChangeAt": 1790069400000,
"serverDay": "2026-09-22",
"serverTime": 3,
"counts": {
"openTasks": 3,
"projects": 3,
"areas": 3
}
}
}
}
```
```bash CLI theme={null}
doers context whoami
```
## send\_flame
**Send a flame.**
The one reaction. One per person per session; a second is a no-op. Only on a session you can see, and never on your own.
| | |
| --------- | -------------------------------------------------------------------------------- |
| Kind | Write · no outside service |
| Auth | Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`) |
| REST | `POST https://api.doers.sh/v2/sessions/{sessionId}/flames` |
| CLI | `doers activity send-flame` |
| Touches | `areas`, `follows`, `projects`, `sessionFlames`, `tasks`, `user`, `workSessions` |
| Operation | `sendFlame` |
### Input
| Field | Type | Required | Default | Allowed values | Description |
| ------------------ | ------ | -------- | ------- | -------------- | --------------------------------- |
| `sessionId` (path) | string | yes | | | *No description in the registry.* |
### Output
| Field | Type | Allowed values | Description |
| ------------------------- | -------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `item` | object | | |
| `item.session` | object | | |
| `item.session.id` | string | | |
| `item.session.startedAt` | number | | Epoch milliseconds. |
| `item.session.endedAt` | number | | Epoch milliseconds. |
| `item.session.visibility` | string | `public`, `anonymized`, `private` | Who sees this task on shared and social surfaces: public shows title and project, anonymized shows only the area, private shows nothing. New tasks default to private. |
| `item.person` | object | | |
| `item.person.username` | string | | |
| `item.person.name` | string | | |
| `item.person.image` | string \| null | | |
| `item.minutes` | integer | 0 to 9007199254740991 | |
| `item.title` | string \| null | | The task's title; the owner always sees it; a follower only when the session is public. |
| `item.container` | string \| null | | The project or area the task lived in, whatever the visibility. |
| `item.flames` | integer | 0 to 9007199254740991 | |
| `item.flamed` | boolean | | Whether the caller sent one. |
| `item.isMe` | boolean | | |
### Example
```json Request theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "send_flame",
"arguments": {
"sessionId": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb"
}
}
}
```
```json Response theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "OK: 🔥 3"
}
],
"structuredContent": {
"item": {
"session": {
"id": "3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb",
"startedAt": 1790069400000,
"endedAt": 1790069400000,
"visibility": "public"
},
"person": {
"username": "ada",
"name": "Acme",
"image": "https://acme.example/ada.png"
},
"minutes": 30,
"title": "Prepare the Acme quarterly review",
"container": "Notes for the Acme launch.",
"flames": 3,
"flamed": true,
"isMe": true
}
}
}
}
```
```bash CLI theme={null}
doers activity send-flame --session-id 3f3af1ec-ebbd-4410-8b41-7ec0d27bbfcb
```