Skip to content
Legion

HTTP API

Generated from packages/envoy/internal/dispatch/api/routes_table.go by docs/site/generators/dispatch-api.ts. Edit the source, not this page.

Dispatch serves 131 routes under /api/v1. A running server lists the same table at GET /api/v1, which needs no credential.

Who may call a route

Section titled “Who may call a route”
  • Anyone: no credential is needed.
  • Human or agent: a signed-in human (browser session) or an agent (bearer token).
  • Human only: a signed-in human; an agent’s bearer token is refused with 403 HUMAN_ONLY.
  • Agent only: an agent’s bearer token; a browser session is refused.

Path parameters are the {name} segments of a path.

Index

Section titled “Index”

GET /api/v1

Section titled “GET /api/v1”

This index: every route with its method, auth, and purpose.

  • Who may call: Anyone

Agents

Section titled “Agents”

GET /api/v1/agents

Section titled “GET /api/v1/agents”

Live sessions with roles, capabilities, open asks, and last activity.

  • Who may call: Human or agent

POST /api/v1/agents/{session_id}/artifacts

Section titled “POST /api/v1/agents/{session_id}/artifacts”

Upload a file or image to an agent’s conversation (multipart, as an issue upload, its kind read from its bytes): ref_key agent/<session_id>/<slug>, addressed dispatch://agent/<session_id>/artifact/<slug>. It holds files and images only: a markdown document (JSON content or a text/markdown file) is 400 ARTIFACT_INPUT, since a document belongs to an issue or a project. No event is appended. A session_id that is empty or holds /, ?, #, whitespace, a control character or a character that ends a reference in text (<>“’`[]|) is 400 INVALID_SESSION_ID on every agent artifact route.

  • Who may call: Human or agent
  • Path parameters: session_id

GET /api/v1/agents/{session_id}/artifacts/{slug}

Section titled “GET /api/v1/agents/{session_id}/artifacts/{slug}”

Read an agent’s conversation’s file or image and its versions by slug.

  • Who may call: Human or agent
  • Path parameters: session_id, slug

GET /api/v1/agents/{session_id}/artifacts/{slug}/versions/{number}

Section titled “GET /api/v1/agents/{session_id}/artifacts/{slug}/versions/{number}”

Download one version of an agent’s conversation’s file or image, as the issue form serves it (Cache-Control: private, max-age=31536000, immutable).

  • Who may call: Human or agent
  • Path parameters: session_id, slug, number

GET /api/v1/agents/{session_id}/messages

Section titled “GET /api/v1/agents/{session_id}/messages”

A session’s targeted messages, newest first.

  • Who may call: Human only
  • Path parameters: session_id

POST /api/v1/agents/{session_id}/messages

Section titled “POST /api/v1/agents/{session_id}/messages”

Send an issue-less targeted message to a session.

  • Who may call: Human only
  • Path parameters: session_id

GET /api/v1/agents/{session_id}/stream

Section titled “GET /api/v1/agents/{session_id}/stream”

Server-sent stream of a live session’s own conversation, relayed from the session itself: an SSE replay event with what the session can still replay, then a frame event per turn, tool call, and streamed update. Nothing is stored.

  • Who may call: Human only
  • Path parameters: session_id

Artifacts

Section titled “Artifacts”

GET /api/v1/artifacts/{id}

Section titled “GET /api/v1/artifacts/{id}”

Read a document’s metadata and current version.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/artifacts/{id}/approval-requests

Section titled “POST /api/v1/artifacts/{id}/approval-requests”

Open an approval ask for a document’s latest version, with an optional summary. A document a human approved before carries that approval on the ask (approval.approved: version, at, by). An open ask follows later versions and waits on its agent until this route hands the same row back to a human.

  • Who may call: Human or agent
  • Path parameters: id

GET /api/v1/artifacts/{id}/asks

Section titled “GET /api/v1/artifacts/{id}/asks”

List a document’s asks.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/artifacts/{id}/asks

Section titled “POST /api/v1/artifacts/{id}/asks”

Open an ask on a document. The response’s advice.suggestions names any already-answered ask that may settle the same question, searched within the document’s project, without ever blocking or slowing the write.

  • Who may call: Human or agent
  • Path parameters: id

GET /api/v1/artifacts/{id}/blocks

Section titled “GET /api/v1/artifacts/{id}/blocks”

A document’s blocks with markdown ranges, tokens, and reference counts; a table block lists its rows and cells by the indexes delete_row and delete_column take.

  • Who may call: Human or agent
  • Path parameters: id

GET /api/v1/artifacts/{id}/blocks/{block_id}

Section titled “GET /api/v1/artifacts/{id}/blocks/{block_id}”

Where one block stands in a document: its path from the top-level block down (type, id, child index), and for a table block, row or cell the table’s id, the row index (0 is the header), the cell’s column index, the text of the header cell drawn above it and the row’s cells; 404 TARGET_NOT_FOUND for an id the live document does not hold.

  • Who may call: Human or agent
  • Path parameters: id, block_id

GET /api/v1/artifacts/{id}/comments

Section titled “GET /api/v1/artifacts/{id}/comments”

List a document’s comments.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/artifacts/{id}/comments

Section titled “POST /api/v1/artifacts/{id}/comments”

Comment on a document or one of its quotes.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/artifacts/{id}/edits

Section titled “POST /api/v1/artifacts/{id}/edits”

Apply quote-anchored edit ops with an optional optimistic-concurrency precondition.

  • Who may call: Human or agent
  • Path parameters: id

GET /api/v1/artifacts/{id}/events

Section titled “GET /api/v1/artifacts/{id}/events”

Page a document’s event log.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/artifacts/{id}/rebuild

Section titled “POST /api/v1/artifacts/{id}/rebuild”

Rebuild a document history ygo cannot load from its latest saved markdown; a live document is 409 DOCUMENT_LIVE and one that loads is 409 DOCUMENT_LOADS.

  • Who may call: Human only
  • Path parameters: id

GET /api/v1/artifacts/{id}/references

Section titled “GET /api/v1/artifacts/{id}/references”

Cross-references to and from a document.

  • Who may call: Human or agent
  • Path parameters: id

GET /api/v1/artifacts/{id}/reviews

Section titled “GET /api/v1/artifacts/{id}/reviews”

List a document’s approval reviews.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/artifacts/{id}/reviews

Section titled “POST /api/v1/artifacts/{id}/reviews”

Approve or request changes on a document’s latest settled version; answers the open approval ask when present, preserving its thread.

  • Who may call: Human only
  • Path parameters: id

GET /api/v1/artifacts/{id}/subscribers

Section titled “GET /api/v1/artifacts/{id}/subscribers”

Sessions subscribed to a document’s topics.

  • Who may call: Human only
  • Path parameters: id

DELETE /api/v1/artifacts/{id}/subscribers/{session_id}

Section titled “DELETE /api/v1/artifacts/{id}/subscribers/{session_id}”

Unsubscribe a session from a document.

  • Who may call: Human only
  • Path parameters: id, session_id

GET /api/v1/artifacts/{id}/text

Section titled “GET /api/v1/artifacts/{id}/text”

A document’s canonical markdown and whole-document token.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/artifacts/{id}/versions

Section titled “POST /api/v1/artifacts/{id}/versions”

Name the current document version.

  • Who may call: Human or agent
  • Path parameters: id

GET /api/v1/artifacts/{id}/versions/{number}

Section titled “GET /api/v1/artifacts/{id}/versions/{number}”

One named or settled document version.

  • Who may call: Human or agent
  • Path parameters: id, number

Asks

Section titled “Asks”

GET /api/v1/asks/open

Section titled “GET /api/v1/asks/open”

Open asks in one scope, with counts: ?author_session= for one session’s own, or ?project= for every open ask on a project’s issues and documents; exactly one is required.

  • Who may call: Human or agent

GET /api/v1/asks/{id}

Section titled “GET /api/v1/asks/{id}”

Read one ask with its replies and edit history.

  • Who may call: Human or agent
  • Path parameters: id

PATCH /api/v1/asks/{id}

Section titled “PATCH /api/v1/asks/{id}”

Reword an open ask (its author or a human); a block ask’s :::ask block is rewritten with it.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/asks/{id}/answer

Section titled “POST /api/v1/asks/{id}/answer”

Answer an ask with selected options and/or text.

  • Who may call: Human only
  • Path parameters: id

GET /api/v1/asks/{id}/followers

Section titled “GET /api/v1/asks/{id}/followers”

List the sessions an ask’s answer and replies reach.

  • Who may call: Human or agent
  • Path parameters: id

DELETE /api/v1/asks/{id}/followers/{session_id}

Section titled “DELETE /api/v1/asks/{id}/followers/{session_id}”

Unfollow an ask (a bearer only for its own session; a human for any).

  • Who may call: Human or agent
  • Path parameters: id, session_id

PUT /api/v1/asks/{id}/followers/{session_id}

Section titled “PUT /api/v1/asks/{id}/followers/{session_id}”

Follow an ask (a bearer only for its own session; a human for any).

  • Who may call: Human or agent
  • Path parameters: id, session_id

POST /api/v1/asks/{id}/resolve

Section titled “POST /api/v1/asks/{id}/resolve”

Retract or resolve an ask without answering it; a block ask’s block records it too.

  • Who may call: Human or agent
  • Path parameters: id

Broadcasts

Section titled “Broadcasts”

GET /api/v1/broadcasts

Section titled “GET /api/v1/broadcasts”

Recent broadcasts, newest first, with their recipient and reply counts.

  • Who may call: Human only

POST /api/v1/broadcasts

Section titled “POST /api/v1/broadcasts”

Send one message to many sessions: one targeted message per recipient under a shared broadcast. A selected session that is not live or does not advertise the mode is excluded and named in the response, never switched to another mode. idempotency_key names one send: a repeat with the same key and request answers the original broadcast (200); a reuse for a different request is 409 BROADCAST_KEY_REUSED naming the broadcast that used it, and sends nothing.

  • Who may call: Human only

GET /api/v1/broadcasts/{id}

Section titled “GET /api/v1/broadcasts/{id}”

One broadcast with every recipient’s delivery attempts and replies, recipients in the order the send named them; a broadcast from before that order was stored falls back to created_at, id.

  • Who may call: Human only
  • Path parameters: id

Comments

Section titled “Comments”

GET /api/v1/comments/{id}

Section titled “GET /api/v1/comments/{id}”

Read one comment with its thread.

  • Who may call: Human or agent
  • Path parameters: id

PATCH /api/v1/comments/{id}

Section titled “PATCH /api/v1/comments/{id}”

Edit a comment’s body.

  • Who may call: Human only
  • Path parameters: id

POST /api/v1/comments/{id}/accept

Section titled “POST /api/v1/comments/{id}/accept”

Accept a suggestion, applying its replacement.

  • Who may call: Human only
  • Path parameters: id

POST /api/v1/comments/{id}/deliveries

Section titled “POST /api/v1/comments/{id}/deliveries”

Retry a comment mention delivery; target is required when it has multiple mentions.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/comments/{id}/reject

Section titled “POST /api/v1/comments/{id}/reject”

Reject a suggestion.

  • Who may call: Human only
  • Path parameters: id

POST /api/v1/comments/{id}/reopen

Section titled “POST /api/v1/comments/{id}/reopen”

Reopen a resolved comment thread.

  • Who may call: Human only
  • Path parameters: id

POST /api/v1/comments/{id}/reply

Section titled “POST /api/v1/comments/{id}/reply”

The mentioned session’s reply to a delivery; the session names itself in actor.

  • Who may call: Agent only
  • Path parameters: id

POST /api/v1/comments/{id}/resolve

Section titled “POST /api/v1/comments/{id}/resolve”

Resolve a comment thread.

  • Who may call: Human or agent
  • Path parameters: id

Credential grants

Section titled “Credential grants”

GET /api/v1/credential-grants

Section titled “GET /api/v1/credential-grants”

List credential grants the caller may revoke (?approver=me only).

  • Who may call: Human only

POST /api/v1/credential-grants/{id}/revoke

Section titled “POST /api/v1/credential-grants/{id}/revoke”

Revoke a credential grant as the caller, its approver or its enrollment’s operator.

  • Who may call: Human only
  • Path parameters: id

Credential requests

Section titled “Credential requests”

GET /api/v1/credential-requests

Section titled “GET /api/v1/credential-requests”

List credential requests the caller may decide (?approver=me only): those naming the caller, a shared secret’s and a service’s machine login, which anyone signed in decides; null without a configured secrets broker.

  • Who may call: Human only

POST /api/v1/credential-requests/machine-lookup

Section titled “POST /api/v1/credential-requests/machine-lookup”

Resolve a pending machine login by its typed confirmation code, returning its facts.

  • Who may call: Human only

GET /api/v1/credential-requests/{id}

Section titled “GET /api/v1/credential-requests/{id}”

Read one credential request’s facts; the broker is authoritative.

  • Who may call: Human only
  • Path parameters: id

POST /api/v1/credential-requests/{id}/approve

Section titled “POST /api/v1/credential-requests/{id}/approve”

Approve a credential request as the caller (a machine login also takes its typed code); the broker decides whether the caller is its approver.

  • Who may call: Human only
  • Path parameters: id

POST /api/v1/credential-requests/{id}/deny

Section titled “POST /api/v1/credential-requests/{id}/deny”

Deny a credential request as the caller (a machine login also takes its typed code); the broker decides whether the caller is its approver.

  • Who may call: Human only
  • Path parameters: id

Delivery

Section titled “Delivery”

GET /api/v1/delivery/measures

Section titled “GET /api/v1/delivery/measures”

The four delivery measures and Sami’s KPI targets for [from, to) (default the last 7 days) and the same facets the timeline takes: deploys a day, lead time (merge, first commit and open to production; open to merge), change failure rate per PR and per deploy (flags_source says whether stored flags fed it), time to restore, rework share, deploy-run success, a per-UTC-day series, the open P0 issues with no owner, and whether each target is met; 404 DELIVERY_NOT_CONFIGURED without a delivery_settings row.

  • Who may call: Human or agent

GET /api/v1/delivery/pipeline

Section titled “GET /api/v1/delivery/pipeline”

The Pipeline page: over the seven UTC days ending today (now, or ?at= for a fixed day), by the day each run started, the PR-checks workflow’s run wall time and success, its five slowest jobs (50 timed results to rank) and the jobs that failed in the last 24 hours, the duration and result of the staging end-to-end, staging deploy and production deploy jobs the settings name in push runs on main, and merge-to-production and PR-open-to-merge per merge day against their targets; not filtered by the timeline’s window or facets; 400 INVALID_QUERY for a malformed at, 404 DELIVERY_NOT_CONFIGURED without a delivery_settings row.

  • Who may call: Human or agent

GET /api/v1/delivery/runs/{id}

Section titled “GET /api/v1/delivery/runs/{id}”

One deploy-repository run with every job it ran, by start, each with its result and timings; 400 RUN_ID_INPUT for an id that is not a positive integer, 404 NOT_FOUND for no such run, 404 DELIVERY_NOT_CONFIGURED without a delivery_settings row.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/delivery/session-groups

Section titled “POST /api/v1/delivery/session-groups”

Create a Delivery session group {name, sessions}: the group becomes the Parent agent of every pull request whose first session it holds; 409 SESSION_IN_GROUP for a session another group holds, 409 SESSION_GROUP_NAME_TAKEN for a name another group has, 409 SESSION_GROUP_NAME_IS_SESSION_TITLE for a name that is the title of a session outside the group. The timeline lists every group (session_groups).

  • Who may call: Human or agent

DELETE /api/v1/delivery/session-groups/{id}

Section titled “DELETE /api/v1/delivery/session-groups/{id}”

Delete a Delivery session group; its sessions show as themselves again.

  • Who may call: Human or agent
  • Path parameters: id

PATCH /api/v1/delivery/session-groups/{id}

Section titled “PATCH /api/v1/delivery/session-groups/{id}”

Rename a Delivery session group, add sessions to it and remove sessions from it {name?, add?, remove?}, with the create route’s refusals; 400 SESSION_GROUP_INPUT for an edit that would leave it empty.

  • Who may call: Human or agent
  • Path parameters: id

GET /api/v1/delivery/timeline

Section titled “GET /api/v1/delivery/timeline”

The delivery timeline within [from, to) (default the last 7 days), the search q (title or PR id) and the given facets (repeatable repo, parent_agent, session, issue, priority (P0-P3), component (a parent includes its children), author, rework, deployed; __no_issue__, __no_priority__, __no_component__ and __no_session__ select by cause): merges with each PR’s issue title, priority and effective components, successful production deploys with every window PR they shipped first, pipeline failures with each run’s production job and failing step, and merged work waiting to deploy, each PR’s deployed_status (deployed, waiting, not_tracked) computed from stored facts; facet_counts (each facet counted with every other facet applied and its own ignored), color_counts (with none applied), the components and issue titles the window names, data freshness, and measures (what GET /api/v1/delivery/measures answers for the same window, search and facets); 404 DELIVERY_NOT_CONFIGURED without a delivery_settings row.

  • Who may call: Human or agent

Events

Section titled “Events”

GET /api/v1/events

Section titled “GET /api/v1/events”

Server-sent event stream; Last-Event-ID or ?since= resumes.

  • Who may call: Human or agent

Inbox

Section titled “Inbox”

GET /api/v1/inbox

Section titled “GET /api/v1/inbox”

Open asks waiting on the caller, grouped by whose turn it is; ?project= and ?assignee=me|unassigned|<email> filter (unassigned includes document asks; an email nobody has signed in with is 400 ASSIGNEE_NOT_ALLOWED).

  • Who may call: Human only

Issues

Section titled “Issues”

GET /api/v1/issues

Section titled “GET /api/v1/issues”

List issues; filters project, status, parent, label, priority (repeatable: 0-3, or none for unset), open, updated_since, route_status (live, no_holder or unknown; open issues only); ?pinned=true is human-only. Each issue carries progress: {tasks, children}, its spec’s task-list items and its direct children as {done, total}, each null when it has none. Pages with limit (1-250) and offset (0 or more; alone it pages 50): a paged answer is {issues, total, limit, offset}, total counting every issue the filters match; without either it is every matching issue as an array. cursor is 400 INVALID_QUERY.

  • Who may call: Human or agent

POST /api/v1/issues

Section titled “POST /api/v1/issues”

Create an issue (native, or from a GitHub owner/repo#n ref); assignee defaults to the creating person, the personal token’s owner, or the parent’s assignee. A title over 1000 characters is 400 CAP_EXCEEDED. The response’s advice.suggestions names the three existing items most like it, found by search, without ever blocking or slowing the write.

  • Who may call: Human or agent

GET /api/v1/issues/resolve

Section titled “GET /api/v1/issues/resolve”

Resolve ?ref=<KEY | owner/repo#n> to an issue key.

  • Who may call: Human or agent

GET /api/v1/issues/{key}

Section titled “GET /api/v1/issues/{key}”

Read an issue with its open asks, primary document, children, and progress: {tasks, children}, its spec’s task-list items (- [ ] / - [x], nested lists included) and its direct children as {done, total}, each null when it has none.

  • Who may call: Human or agent
  • Path parameters: key

PATCH /api/v1/issues/{key}

Section titled “PATCH /api/v1/issues/{key}”

Update title (over 1000 characters is 400 CAP_EXCEEDED), status, priority, labels (or labels_add, which adds to the labels the issue holds when the write commits rather than replacing them; not with labels), route, parent, rank, assignee (the email of a person who has signed in, or null; anyone may reassign), or components ({mode: inherit|explicit|none, ids, reason}; allowed on a closed issue). expected_sequence makes the write conditional: 409 ISSUE_CHANGED when the issue’s last event is no longer that sequence.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/issues/{key}/artifacts

Section titled “GET /api/v1/issues/{key}/artifacts”

List an issue’s documents and files.

  • Who may call: Human or agent
  • Path parameters: key

POST /api/v1/issues/{key}/artifacts

Section titled “POST /api/v1/issues/{key}/artifacts”

Upload an issue document or file (JSON or multipart). A text/markdown upload is a document; any other is an image only when its bytes are a PNG, JPEG, GIF or WebP, stored under the type its bytes are whatever was declared, and otherwise a file under its declared type.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/issues/{key}/artifacts/{slug}

Section titled “GET /api/v1/issues/{key}/artifacts/{slug}”

Read an issue document by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

GET /api/v1/issues/{key}/artifacts/{slug}/blocks

Section titled “GET /api/v1/issues/{key}/artifacts/{slug}/blocks”

An issue document’s blocks and tokens, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

POST /api/v1/issues/{key}/artifacts/{slug}/edits

Section titled “POST /api/v1/issues/{key}/artifacts/{slug}/edits”

Apply edit ops with an optional optimistic-concurrency precondition to an issue document, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

GET /api/v1/issues/{key}/artifacts/{slug}/text

Section titled “GET /api/v1/issues/{key}/artifacts/{slug}/text”

An issue document’s canonical markdown and whole-document token, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

POST /api/v1/issues/{key}/artifacts/{slug}/versions

Section titled “POST /api/v1/issues/{key}/artifacts/{slug}/versions”

Name the current version of an issue document, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

GET /api/v1/issues/{key}/artifacts/{slug}/versions/{number}

Section titled “GET /api/v1/issues/{key}/artifacts/{slug}/versions/{number}”

One version of an issue document, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug, number

GET /api/v1/issues/{key}/asks

Section titled “GET /api/v1/issues/{key}/asks”

List an issue’s asks; ?state= filters.

  • Who may call: Human or agent
  • Path parameters: key

POST /api/v1/issues/{key}/asks

Section titled “POST /api/v1/issues/{key}/asks”

Open a question ask on an issue (options optional). The response’s advice.suggestions names any already-answered ask that may settle the same question, with who answered and when, without ever blocking or slowing the write.

  • Who may call: Human or agent
  • Path parameters: key

DELETE /api/v1/issues/{key}/claim

Section titled “DELETE /api/v1/issues/{key}/claim”

Release the issue’s claim: its holder, any human, or anyone when the holding session is no longer live. The status does not move. 409 ISSUE_CLAIMED names the holder this caller may not release (there is no force on this route); 409 CLAIM_CONTENDED means the holder changed twice while the request ran, so nothing was applied and nobody’s liveness was checked.

  • Who may call: Human or agent
  • Path parameters: key

POST /api/v1/issues/{key}/claim

Section titled “POST /api/v1/issues/{key}/claim”

Claim the issue for the calling session (or human): records who is working it. The status does not move. 409 ISSUE_CLAIMED names a live holder (or a human one, whose claim has no session to end); a human may pass {force: true} to take it anyway. 409 CLAIM_CONTENDED means the holder changed twice while the request ran, so nothing was applied and nobody’s liveness was checked: read the issue and retry.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/issues/{key}/comments

Section titled “GET /api/v1/issues/{key}/comments”

List an issue’s comments; ?artifact= scopes to a document.

  • Who may call: Human or agent
  • Path parameters: key

POST /api/v1/issues/{key}/comments

Section titled “POST /api/v1/issues/{key}/comments”

Comment on an issue, a document quote, or an ask.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/issues/{key}/events

Section titled “GET /api/v1/issues/{key}/events”

Page an issue’s event log (after, before, ids, order, limit).

  • Who may call: Human or agent
  • Path parameters: key

POST /api/v1/issues/{key}/messages

Section titled “POST /api/v1/issues/{key}/messages”

Post an issue message; target and delivery address a session or role.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/issues/{key}/messages/{id}

Section titled “GET /api/v1/issues/{key}/messages/{id}”

Read one message with its deliveries and replies.

  • Who may call: Human or agent
  • Path parameters: key, id

GET /api/v1/issues/{key}/references

Section titled “GET /api/v1/issues/{key}/references”

Cross-references to and from an issue.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/issues/{key}/subscribers

Section titled “GET /api/v1/issues/{key}/subscribers”

Sessions subscribed to an issue’s topics.

  • Who may call: Human only
  • Path parameters: key

DELETE /api/v1/issues/{key}/subscribers/{session_id}

Section titled “DELETE /api/v1/issues/{key}/subscribers/{session_id}”

Unsubscribe a session from an issue.

  • Who may call: Human only
  • Path parameters: key, session_id

Machine logins

Section titled “Machine logins”

GET /api/v1/machine-logins

Section titled “GET /api/v1/machine-logins”

List the machine logins the caller may revoke that can still reach a secret: the secrets broker’s launcher credentials for every service’s login, whoever approved it, and for the caller’s own machines, unexpired or expired with a session still running, each naming who approved it.

  • Who may call: Human only

POST /api/v1/machine-logins/{id}/revoke

Section titled “POST /api/v1/machine-logins/{id}/revoke”

Revoke a machine login, expired or not, ending every session it enrolled, a service’s pods included: anyone signed in revokes a service’s login, and only the person who approved a person’s machine login revokes that one.

  • Who may call: Human only
  • Path parameters: id

Me

Section titled “Me”

GET /api/v1/me/agent-tokens

Section titled “GET /api/v1/me/agent-tokens”

List the caller’s personal agent tokens.

  • Who may call: Human only

POST /api/v1/me/agent-tokens

Section titled “POST /api/v1/me/agent-tokens”

Mint a personal agent token.

  • Who may call: Human only

DELETE /api/v1/me/agent-tokens/{id}

Section titled “DELETE /api/v1/me/agent-tokens/{id}”

Revoke a personal agent token.

  • Who may call: Human only
  • Path parameters: id

GET /api/v1/me/agents/state

Section titled “GET /api/v1/me/agents/state”

The caller’s per-agent conversation state: cleared_before, read_through, and unread_replies (the session’s replies to the caller’s direct messages newer than both and not read by id).

  • Who may call: Human only

PUT /api/v1/me/agents/{session_id}/state

Section titled “PUT /api/v1/me/agents/{session_id}/state”

Clear an agent’s conversation for the caller (cleared_before hides exchanges at or before it), mark it read (read_through only moves forward), and/or mark some of its replies read by id (read_replies, the session’s own messages); answers the session’s state.

  • Who may call: Human only
  • Path parameters: session_id

GET /api/v1/me/answers

Section titled “GET /api/v1/me/answers”

The caller’s own answers and replies on asks across issues and project documents, newest first: each row is an answer (the ask.answered event’s answer, and whether it is still the ask’s current one) or a reply, with the ask’s question, state, owner and deep link; pages with limit (1-200, default 50) and offset; {rows, total, limit, offset}.

  • Who may call: Human only

DELETE /api/v1/me/asks/{id}/snooze

Section titled “DELETE /api/v1/me/asks/{id}/snooze”

Un-snooze an inbox row for the caller.

  • Who may call: Human only
  • Path parameters: id

PUT /api/v1/me/asks/{id}/snooze

Section titled “PUT /api/v1/me/asks/{id}/snooze”

Snooze an inbox row for the caller until snoozed_until.

  • Who may call: Human only
  • Path parameters: id

PUT /api/v1/me/issues/{key}/state

Section titled “PUT /api/v1/me/issues/{key}/state”

Update the caller’s read state for an issue.

  • Who may call: Human only
  • Path parameters: key

GET /api/v1/me/replies

Section titled “GET /api/v1/me/replies”

The threads the caller wrote in (an ask, a comment thread, an issue message thread) where someone else has written since the caller last read it, newest reply first, less an open ask the Inbox lists: each row names the thread, its owner, its subject, its root’s deep link and the newest reply’s author, first line and time. ?issue= or ?artifact= narrows to one owner (both is 400 INVALID_QUERY); pages with limit (1-200, default 50) and offset; {rows, total, limit, offset}.

  • Who may call: Human only

GET /api/v1/me/state

Section titled “GET /api/v1/me/state”

The caller’s per-issue read state.

  • Who may call: Human only

PUT /api/v1/me/threads/{id}/read

Section titled “PUT /api/v1/me/threads/{id}/read”

Move the caller’s read mark on one thread forward to {read_through} (RFC3339; stored as no later than now; more than a minute ahead of the server is 400 INVALID_STATE). It only moves forward; a thread the caller never wrote in writes nothing; 204 either way. A non-uuid id is 400 THREAD_ID_INPUT.

  • Who may call: Human only
  • Path parameters: id

Messages

Section titled “Messages”

GET /api/v1/messages/{id}

Section titled “GET /api/v1/messages/{id}”

Read the conversation a message belongs to by any message id in it, issue-less or not: the thread root with its deliveries and every reply, oldest first. An issue thread follows the issue’s rule. On a direct (issue-less) thread a bearer names its session in ?session= and reads only one whose root targets that session or that it replied in (403 THREAD_FORBIDDEN), a guard against reading another session’s conversation by mistake, not an authorization boundary. Direct-conversation text also reaches every authenticated caller through GET /api/v1/events; nothing in Dispatch restricts it by session.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/messages/{id}/deliveries

Section titled “POST /api/v1/messages/{id}/deliveries”

Retry delivering a targeted message.

  • Who may call: Human or agent
  • Path parameters: id

POST /api/v1/messages/{id}/deliveries/{attempt}/accept

Section titled “POST /api/v1/messages/{id}/deliveries/{attempt}/accept”

The attempt’s session records that it took the message as its user’s own turn; the session names itself in actor (403 ACCEPT_FORBIDDEN for another’s attempt). One compare-and-set: only a direct message to that session, on no issue, neither a broadcast’s copy nor a reply in a broadcast’s thread, in a thread whose root targets it (409 ACCEPT_NOT_DIRECT), that a person wrote (409 ACCEPT_NOT_WRITTEN_BY_PERSON), sent as a Send or an Aside (409 ACCEPT_NOT_ASIDE_OR_STEER); only the message’s latest attempt (409 ACCEPT_SUPERSEDED), when no attempt of it was accepted before (409 ACCEPT_ALREADY_ACCEPTED), which a person requested (409 ACCEPT_NOT_REQUESTED_BY_PERSON), that person being the message’s author (409 ACCEPT_NOT_REQUESTED_BY_AUTHOR), which did not fail (409 ACCEPT_FAILED; a pending or sent attempt is taken), within the last minute (409 ACCEPT_STALE). Answers the attempt with accepted_at and accepted_as and the message’s stored body; leaves the attempt’s state to the send, and appends message.accepted.

  • Who may call: Agent only
  • Path parameters: id, attempt

POST /api/v1/messages/{id}/reply

Section titled “POST /api/v1/messages/{id}/reply”

The targeted session’s reply to a delivery; the session names itself in actor. Once the attempt is answered, ?follow_up=true posts other text as the session’s follow-up, threaded under its first reply; with follow_up=false or absent, or with text the session already posted there, nothing is posted and the stored message comes back marked duplicate. Any other follow_up is 400 MESSAGE_INPUT.

  • Who may call: Agent only
  • Path parameters: id

Projects

Section titled “Projects”

GET /api/v1/projects

Section titled “GET /api/v1/projects”

List projects.

  • Who may call: Human or agent

POST /api/v1/projects

Section titled “POST /api/v1/projects”

Create a project {key, name}: any signed-in person or agent session; a bearer names its session in actor. A key that is not a project key, an empty name, a name holding a control character or a bidi embedding, override or isolate, or a name with no visible character (a letter, number, punctuation or symbol other than the blank fillers U+115F, U+1160, U+3164, U+FFA0 and U+2800, or a code point Go’s Unicode tables leave unassigned, such as an emoji newer than them, other than a noncharacter (U+FDD0-U+FDEF and each code point ending in FFFE or FFFF) or a reserved default-ignorable (U+2065, U+FFF0-U+FFF8, U+E0000-U+E0FFF); combining marks, format characters, private-use characters and whitespace don’t count) is 400 INVALID_PROJECT; a name over 80 characters is 400 CAP_EXCEEDED; a key that already exists is 409 PROJECT_EXISTS.

  • Who may call: Human or agent

GET /api/v1/projects/{key}/architecture

Section titled “GET /api/v1/projects/{key}/architecture”

A project’s component tree with the work attached: per-component counts and issue rows, plus unassigned, not-architectural, and retired-link issues; 404 SOURCE_NOT_FOUND without a source.

  • Who may call: Human or agent
  • Path parameters: key

DELETE /api/v1/projects/{key}/architecture-source

Section titled “DELETE /api/v1/projects/{key}/architecture-source”

Remove a project’s architecture source.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/projects/{key}/architecture-source

Section titled “GET /api/v1/projects/{key}/architecture-source”

A project’s architecture source, or null when it has none.

  • Who may call: Human or agent
  • Path parameters: key

PUT /api/v1/projects/{key}/architecture-source

Section titled “PUT /api/v1/projects/{key}/architecture-source”

Set a project’s architecture source {repo, branch} after proving the GitHub App can read it.

  • Who may call: Human or agent
  • Path parameters: key

POST /api/v1/projects/{key}/architecture-source/sync

Section titled “POST /api/v1/projects/{key}/architecture-source/sync”

Import a project’s architecture model from its source now; 200 carries the updated row (last_error set when the import failed), 409 SOURCE_ACCESS a credential or branch problem.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/projects/{key}/artifacts

Section titled “GET /api/v1/projects/{key}/artifacts”

List a project’s documents.

  • Who may call: Human or agent
  • Path parameters: key

POST /api/v1/projects/{key}/artifacts

Section titled “POST /api/v1/projects/{key}/artifacts”

Upload a project document or file (JSON or multipart); a file’s kind is read from its bytes, as an issue upload’s is.

  • Who may call: Human or agent
  • Path parameters: key

GET /api/v1/projects/{key}/artifacts/{slug}

Section titled “GET /api/v1/projects/{key}/artifacts/{slug}”

Read a project document by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

GET /api/v1/projects/{key}/artifacts/{slug}/blocks

Section titled “GET /api/v1/projects/{key}/artifacts/{slug}/blocks”

A project document’s blocks and tokens, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

POST /api/v1/projects/{key}/artifacts/{slug}/edits

Section titled “POST /api/v1/projects/{key}/artifacts/{slug}/edits”

Apply edit ops with an optional optimistic-concurrency precondition to a project document, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

GET /api/v1/projects/{key}/artifacts/{slug}/text

Section titled “GET /api/v1/projects/{key}/artifacts/{slug}/text”

A project document’s canonical markdown and whole-document token, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

POST /api/v1/projects/{key}/artifacts/{slug}/versions

Section titled “POST /api/v1/projects/{key}/artifacts/{slug}/versions”

Name the current version of a project document, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug

GET /api/v1/projects/{key}/artifacts/{slug}/versions/{number}

Section titled “GET /api/v1/projects/{key}/artifacts/{slug}/versions/{number}”

One version of a project document, by slug or unambiguous filename.

  • Who may call: Human or agent
  • Path parameters: key, slug, number

References

Section titled “References”

GET /api/v1/references

Section titled “GET /api/v1/references”

Edges of one node in the reference graph: ?to=<dispatch ref> backlinks or ?from= links; ?kind=, ?since=<events.id> (mentions only).

  • Who may call: Human or agent

Schema

Section titled “Schema”

GET /api/v1/schema/blocks

Section titled “GET /api/v1/schema/blocks”

The typed document block schema as JSON.

  • Who may call: Anyone
Section titled “Search”

GET /api/v1/search

Section titled “GET /api/v1/search”

Full-text search ?q= across issues, documents, asks, comments, and messages, within ?project= when given: each kind ranked on its own and merged by reciprocal rank fusion, one page of ?limit= (1-50, default 20) from ?offset=, with the total match count and how many the pages can reach (each kind’s best 100); a q over 1000 characters is 400 CAP_EXCEEDED, and a project that is not a project key is 400 INVALID_PROJECT.

  • Who may call: Human or agent

Settings

Section titled “Settings”

GET /api/v1/settings/architecture-sources

Section titled “GET /api/v1/settings/architecture-sources”

List every project’s architecture source.

  • Who may call: Human or agent

GET /api/v1/settings/delivery

Section titled “GET /api/v1/settings/delivery”

The delivery timeline’s one configuration record (deploy repository, workflow paths, production job names, optional production apply step, population authors, excluded repositories, and the Pipeline page’s optional staging end-to-end, staging deploy and PR-checks roll-up job names), or null when it has not been set.

  • Who may call: Human or agent

PUT /api/v1/settings/delivery

Section titled “PUT /api/v1/settings/delivery”

Set the delivery timeline’s configuration after proving the GitHub App can read the deploy repository; 409 DELIVERY_SETTINGS_ACCESS a credential or repository problem.

  • Who may call: Human or agent

GET /api/v1/settings/repo-projects

Section titled “GET /api/v1/settings/repo-projects”

List GitHub repository to project mappings, each marked whether it is its project’s default.

  • Who may call: Human or agent

DELETE /api/v1/settings/repo-projects/{owner}/{repo}

Section titled “DELETE /api/v1/settings/repo-projects/{owner}/{repo}”

Remove a repository mapping no issue names as its repo.

  • Who may call: Human or agent
  • Path parameters: owner, repo

PUT /api/v1/settings/repo-projects/{owner}/{repo}

Section titled “PUT /api/v1/settings/repo-projects/{owner}/{repo}”

Map a GitHub repository to a project {project, default?}; default true makes it the project’s one default.

  • Who may call: Human or agent
  • Path parameters: owner, repo

Users

Section titled “Users”

GET /api/v1/users

Section titled “GET /api/v1/users”

Everyone who has signed in, by lowercase email: the assignee picker’s options.

  • Who may call: Human only

Whoami

Section titled “Whoami”

GET /api/v1/whoami

Section titled “GET /api/v1/whoami”

Who the server takes the caller for: {kind: user, login} (login is the person’s lowercase email) or {kind: agent, owner, service} (owner is a personal token’s owner by lowercase email, null for the shared token; service is a verified service-account token’s Kubernetes subject, null otherwise).

  • Who may call: Human or agent