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

# REST API

> Conventions, the permission model, and the complete endpoint reference.

Call more than 470 operations under `/v1`.

<Card title="Open the full API reference" icon="book" href="https://docket-api.hypertext.studio/v1/docs" horizontal>
  Every endpoint and field, with a request playground.
</Card>

<Note>
  **`/v1/docs` is the source of truth for endpoint detail.** Where it and these pages disagree,
  believe it.
</Note>

Generate a client from
[`/v1/openapi.json`](https://docket-api.hypertext.studio/v1/openapi.json). Docket publishes no SDK.
See [Platform status](/docs/developers/platform-status).

## Authentication

Send a bearer token on every request:

```http theme={"dark"}
Authorization: Bearer <token>
```

**Only `GET /v1/config` works without one.** See [Authentication](/docs/developers/authentication) to
get one.

## What shapes your client

Four things decide how you build against `/v1`. The reference documents the rest, including
idempotency, conditional requests with `ETag`, content negotiation, and caching.

* **IDs are ULIDs, branded per entity type.** Pass a `TaskId` to a parameter typed `ProjectId` and
  the call fails. Never parse one.
* **Pagination is keyset.** Pass `cursor` and `limit`, read `nextCursor`, stop when it is `null`.
* **Failures are RFC 9457 problem documents.** Branch on `code`. See [Errors](/docs/developers/errors).
* **Requests and responses share one schema.** A response that does not match what `/v1/docs`
  renders is a bug.

## Permissions

**Membership.** Every `/v1/orgs/{orgId}/*` route needs an active Actor. Docket returns **404** to
non-members, never 403. Probing tells you nothing.

**Capability.** Mutations need a capability on the ladder:

```
view  <  comment  <  contribute  <  assign  <  manage
```

Reassign a task, you need `assign`. Post a comment, `comment`. Rename the workspace, `manage`. Read
endpoints apply the permission predicate inside the query. Skip the client-side filter.
Agents pass the identical checks, plus the
[approval gate](/docs/guides/athena/proposals-and-approvals).

## Cross-workspace reads

The Hub (`/hub/today`, `/portfolio`, `/search`, `/inbox`, `/activity`), notifications, and the
personal daily plan read every workspace you are a member of. Docket runs **one permission-scoped
query per membership** and merges the results in application code. No SQL join crosses tenants.

## Resource groups

| Group                                                                      | Covers                             |
| -------------------------------------------------------------------------- | ---------------------------------- |
| [Orgs](https://docket-api.hypertext.studio/v1/docs#tag/orgs)               | Workspaces, the tenant boundary    |
| [Teams](https://docket-api.hypertext.studio/v1/docs#tag/teams)             | Teams and their workflow states    |
| [Tasks](https://docket-api.hypertext.studio/v1/docs#tag/tasks)             | Subtasks and dependencies          |
| [Projects](https://docket-api.hypertext.studio/v1/docs#tag/projects)       | Bounded efforts and milestones     |
| [Programs](https://docket-api.hypertext.studio/v1/docs#tag/programs)       | Ongoing areas of operation         |
| [Initiatives](https://docket-api.hypertext.studio/v1/docs#tag/initiatives) | Strategic themes                   |
| [Cycles](https://docket-api.hypertext.studio/v1/docs#tag/cycles)           | Team time windows                  |
| [Updates](https://docket-api.hypertext.studio/v1/docs#tag/updates)         | Narrative status and health        |
| [Comments](https://docket-api.hypertext.studio/v1/docs#tag/comments)       | Threaded discussion                |
| [Agents](https://docket-api.hypertext.studio/v1/docs#tag/agents)           | Agents and their sessions          |
| [Hub](https://docket-api.hypertext.studio/v1/docs#tag/hub)                 | Cross-workspace reads              |
| [Me](https://docket-api.hypertext.studio/v1/docs#tag/me)                   | Connections, sessions, preferences |

## Live updates

Open `GET /v1/stream/sse` and Docket sends `stream-event` frames, with a ping every 25 seconds.
Cannot open a long-lived connection? Poll `/v1/hub/stream` and `/v1/orgs/{orgId}/stream`.

<Warning>
  Docket sends **no outbound webhooks**. To react to changes, poll a stream endpoint or subscribe
  over [MCP](/docs/developers/mcp-tools-and-resources#subscriptions).
</Warning>

## REST or MCP?

The [MCP server](/docs/developers/connect-an-agent-mcp) calls the identical service layer beneath the
same permission engine. Use REST when you know which record you want and which fields to set. Use
MCP when your caller describes intent: tools take names anywhere IDs go, and `organize` applies a
whole plan in one call.