API reference

The Orchestrat server speaks JSON over HTTP. The dashboard, the CLI and the MCP bridge all use the routes on this page. Examples use http://localhost:8801.

Request and response shapes are Zod schemas in packages/protocol; treat them as the source of truth for field-level detail.

Conventions

• Prefixes. Routes for people live under /api/v1. Routes for agents live under /api/v1/agent. A few public routes need no token; see Public routes.
• Status codes. Creates return 201 and queued work returns 202. Repository and integration deletes return 204 with no body. Everything else returns 200.
• IDs are UUIDs, and timestamps are ISO 8601 strings.
• Request IDs. Every response has an x-request-id header, also echoed in error bodies.
• Pagination. List routes take limit (1–100, default 50) and an opaque cursor, and return next_cursor (null on the last page). Event lists use after instead of cursor. A malformed cursor returns 400 VALIDATION_ERROR.
• Optimistic concurrency. Task writes send the task's current expected_version; a stale one returns 409 TASK_VERSION_CONFLICT with current_version when known. Document writes send base_revision; a stale one returns 409 DOCUMENT_CONFLICT with current_revision and base_revision. Successful writes bump the version.
• Archived projects stay readable; writes return 409 PROJECT_ARCHIVED.

Idempotency keys

Some creates require an Idempotency-Key header of 1–128 characters. Repeating a request with the same key returns the original response. Reusing the key for a different request returns 409 IDEMPOTENCY_CONFLICT. A missing key returns 400 VALIDATION_ERROR.

Keys are scoped to the caller (person or agent). Task and chat creation keys are also scoped to the branch, so one key on two branches creates two items. Merge keys are scoped to the person and the target branch.

The key is required on:

• task, comment and bulk task creation (people and agents)
• chat creation and chat messages (people and agents)
• handoffs (people and agents)
• POST /api/v1/agent/hooks/lifecycle
• POST /api/v1/projects/:projectId/merges

Authentication

People

People send an access token on every /api/v1 route except the public ones:

Authorization: Bearer orch_sess_<token>

Sign-up, sign-in and refresh return a session. Shapes are in packages/protocol/src/auth.ts:

{
  "access_token": "orch_sess_…",
  "refresh_token": "orch_refresh_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_expires_in": 2592000,
  "user": {
    "user_id": "…",
    "email": "you@example.com",
    "full_name": "…",
    "is_instance_admin": true
  },
  "invited_project_id": null
}

The access token lasts 1 hour and the refresh token 30 days. Refreshing returns a new pair and retires the old refresh token. Presenting the previous refresh token more than 60 seconds after it was replaced ends the session, because it may have leaked. A session ends 90 days after sign-in, however often it is refreshed. Session responses carry Cache-Control: no-store.

Emails are trimmed and lowercased, up to 320 characters. Passwords are 10 to 256 characters, and full_name 1 to 120. Sign-up follows ORCHESTRAT_SIGNUP: with invite (the default) it needs a valid, unused invite_token, which the sign-up uses up. See Users and accounts.

A missing, expired or revoked access token returns 401 UNAUTHENTICATED. A request for a project you can't access returns 403 PERMISSION_DENIED. An agent token sent to a human route returns 401 AGENT_CREDENTIAL_INVALID.

Agents

Agents call routes under /api/v1/agent with exactly one Authorization header holding an agent token:

Authorization: Bearer orch_agent_<token>

• An agent token belongs to one agent in one project. The server takes the agent and project from the token; IDs in paths and bodies never change them.
• Tokens are random, stored only as hashes, and returned once, when issued.
• A missing, malformed or unknown token returns 401 AGENT_CREDENTIAL_INVALID. A revoked token, or a token of a revoked agent, returns 401 AGENT_CREDENTIAL_REVOKED immediately.
• Agents name a branch with X-Orchestrat-Branch-Id or pin requests to a session with X-Orchestrat-Session-Id; see Choosing a branch.

Agent tokens are minted in two ways: by the CLI's browser approval (below), or by a project owner or admin through Agents and credentials.

CLI browser approval

orchestrat setup uses these routes to get a CLI credential and then one agent token per integration.

integration is one of codex, claude-code, cursor, antigravity or opencode. The CLI credential is sent as Authorization: Bearer orch_cli_… and works only on the /api/v1/cli/setup routes. An invalid one returns 401 UNAUTHENTICATED.

Errors

Errors share one envelope:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "You do not have access to this project.",
    "details": {},
    "request_id": "req_…"
  }
}

Schema validation failures return 400 VALIDATION_ERROR with the validation issues in details; an oversized body returns 413 VALIDATION_ERROR. Some codes add a details.reason, listed per area below.

Rate limits

Limits are fixed windows kept in the server's memory, one minute unless the table says otherwise. A limited request returns 429 RATE_LIMITED with a Retry-After header and details.retry_after_seconds.

Limits per IP see the client's address only when the server trusts its reverse proxy; set ORCHESTRAT_TRUST_PROXY_HOPS behind one. See Configuration.

The attention routes have their own limits: WAIT_LIMIT caps concurrent long-polls, and HANDOFF_RATE_LIMITED, HANDOFF_CHAIN_LIMIT and WAKE_LIMIT stop handoff and wake loops.

Public routes

These routes take no session or agent token.

The instance, signup, login, refresh and revoke auth routes are also public (see People), and so are the CLI authorization attempts and poll routes (see CLI browser approval).

When the server serves the dashboard, every other GET outside /api, /health and /ready returns the dashboard's index.html, so client-side routes load directly.

Profile

Organizations

Roles are owner, admin and member. Slugs are optional and derived from the name when omitted.

Projects

Project creation accepts name, optional slug, description and task_key_prefix (2–8 letters or digits, uppercased). Without a prefix, the server uses the first three alphanumeric characters of the slug when at least two exist, otherwise PRJ.

Members and invitations

Access to a project needs membership in both the organization and the project.

Tasks

• Fields. id, project_id, branch_id, key, title, description, priority, status, position, version, created_by, created_by_user_id, created_at, updated_at, started_at, completed_at, cancelled_at. Cards add comment_count and unresolved_blocker_count. created_by says whether a person or an agent created the task; the legacy created_by_user_id is null for agent-created tasks.
• Values. Priorities: urgent, high, medium, low, none. Statuses: backlog, ready, claimed, in_progress, blocked, review, done, cancelled. People can't select claimed; only the agent claim flow sets it.
• Create takes title, optional description, priority (default none) and status (default backlog). The task is appended to its status column.
• List takes status, priority, limit and cursor, ordered by position then ID. It returns { tasks, total, next_cursor }, where total counts every match on the branch.
• Move takes status, optional before_task_id (an anchor in the target column) and expected_version. Entering in_progress, done or cancelled sets the matching timestamp; leaving the status clears it.
• Comments are immutable Markdown in body_markdown, with a per-task sequence and up to 20 mentions. Reads return { comments, next_cursor }.
• Dependencies stay on one branch: a dependency on another branch's task returns 400 VALIDATION_ERROR with reason: "cross_branch". A self-edge or cycle returns 409 TASK_DEPENDENCY_CYCLE.

Agents and credentials

Presence and events

• An agent is online when it has an active session with a heartbeat in the last 60 seconds. Its branch_id is its session's branch, or null when offline.
• Events are ordered by numeric event ID. Pass the previous response's next_cursor as after.
• Each event has a branch_id, or null for project-wide events (branches, repository, agents, credentials). A branch's list includes its own events plus the project-wide ones. all_branches=true returns every branch; the dashboard's realtime catch-up uses it to keep one cursor.

Documents

• Paths are relative POSIX paths of 1–1024 characters ending in .md, with no leading slash, backslash, NUL, empty segment, or ./.. segment. Paths are unique per branch.
• Content is Markdown text up to 1,000,000 characters.
• Writes create one immutable revision and advance current_revision atomically. A stale base_revision returns 409 DOCUMENT_CONFLICT and writes nothing:

{
  "error": {
    "code": "DOCUMENT_CONFLICT",
    "message": "Document revision is stale.",
    "details": { "current_revision": 2, "base_revision": 1 },
    "request_id": "req_…"
  }
}

• Edits apply up to 1,000 exact replacements in order. Each old_text must match exactly once, otherwise 409 DOCUMENT_EDIT_MISMATCH with edit_index and match_count.
• Lists are ordered by update time, then ID.

Create and update responses contain the document and its new revision:

{
  "document": {
    "id": "…",
    "project_id": "…",
    "path": "docs/readme.md",
    "current_revision": 1,
    "created_by": { "type": "human", "id": "…" },
    "created_at": "2026-10-14T00:00:00.000Z",
    "updated_at": "2026-10-14T00:00:00.000Z"
  },
  "revision": {
    "id": "…",
    "document_id": "…",
    "revision_number": 1,
    "content": "# Notes",
    "author": { "type": "human", "id": "…" },
    "created_at": "2026-10-14T00:00:00.000Z"
  }
}

Attachments

Attachments need object storage; without it, uploads and downloads return 503 STORAGE_UPLOAD_FAILED.

The server never receives upload bytes. Starting an upload returns either a single presigned upload_url or a multipart upload with part_size_bytes; the client sends bytes straight to the bucket, then calls complete. Uploads expire after 24 hours unless refreshed. Files are limited to 2 GiB, and a project's attachments count toward its quota (409 ATTACHMENT_QUOTA_EXCEEDED). Downloads stream through the server from /api/v1/attachments/download.

Chats

Participants are { type, id } with type human or agent. A message holds up to 100 mentions and 20 document references; documents must be on the chat's branch.

Attention and handoffs

• A handoff is a direct message to to with an optional task reference. Its body is up to 4,000 characters.
• An agent can't complete or release a claim, or move its task to review or done, while comments by others posted since the claim are unacknowledged: 409 TASK_COMMENTS_UNREAD. Sending acknowledged_through (a comment sequence) clears it. Imported comments never count.
• Attention events: task.status_changed, task.block_resolved, chat.handoff_created (its entity is the chat, so chat access rules apply), and run.woken. task.comment_created adds sequence and mentions; claim.released adds reason.

Agent routes are under Agent attention and handoffs. How attention works: Architecture.

Branches

Every project has branches, and exactly one is the default. Tasks (with comments, dependencies and claims), documents (with folders, revisions and attachments), chats (with participants and messages) and agent sessions belong to one branch. Organizations, projects, members, agents and credentials are project-wide. Project responses include default_branch_id. How branches work: Architecture.

Choosing a branch

A request that names no branch uses the default branch, so clients written before branches keep working.

People. These routes take an optional branch_id query parameter:

• GET and POST /api/v1/projects/:projectId/tasks
• GET and POST /api/v1/projects/:projectId/documents
• POST /api/v1/projects/:projectId/document-folders
• GET and POST /api/v1/projects/:projectId/chats
• GET /api/v1/projects/:projectId/inbox
• GET /api/v1/projects/:projectId/events
• POST /api/v1/projects/:projectId/handoffs

A branch_id outside the project returns 404 BRANCH_NOT_FOUND. Archived branches stay readable; a create on one returns 409 BRANCH_ARCHIVED. Routes for a single task, document, attachment or chat take the branch from that item. Presence, message candidates and the human attention routes are project-wide.

Agents. Agent routes resolve the branch in this order:

1. Pinned session. X-Orchestrat-Session-Id: <session id> uses that session's branch. A claim uses the session in its body. If X-Orchestrat-Branch-Id names a different branch, the request fails with 409 BRANCH_MISMATCH. A session that isn't the agent's returns 404 AGENT_SESSION_NOT_FOUND.
2. Header. X-Orchestrat-Branch-Id: <branch id>.
3. The default branch.

Both headers must be UUIDs; a malformed value returns 400 VALIDATION_ERROR with details.header. Agents can read tasks, documents and chats on any branch by ID. A write to an item on a different branch than the one named or pinned returns 409 BRANCH_MISMATCH; a write with no branch signal uses the item's branch.

New branch error codes go only to requests that name a branch (?branch_id=, X-Orchestrat-Branch-Id or X-Orchestrat-Session-Id) and to the branch, merge, decision and repository routes. Other requests get an existing code with a details.reason:

Cross-branch references are task dependencies, blocking tasks, the task in a handoff, and document_ids in chat messages.

Branch routes

A branch is { id, project_id, name, is_default, name_source, created_via, created_by, onboarding_state, onboarding_choice, archived_at, archived_reason, provider, open_decision_count, created_at, updated_at }. provider is null without a connected repository, otherwise { provider, state, head_sha } with state tracked, missing or untracked. archived_reason is provider_deleted, manual or replaced_on_connect.

Branch names are 1–255 characters and follow a subset of git check-ref-format: no spaces, control characters or ~ ^ : ? * [ \; no leading - or /; no trailing / or .lock; no .., // or @{; and not @. Names are unique among active branches only.

Imports, merges and decisions

People only. Agents can't archive, merge, import, set the default or resolve decisions.

• Who. kind is import or merge. Members import into any branch except the default. A merge, an import into the default branch, and archive_source: true need an owner or admin, for the preview as well as the apply.
• Selection. An import takes { tasks, documents, chats }, each "all" or a list of up to 2,000 lineage keys. A merge always takes everything. Selecting a task also brings the tasks it depends on that the target lacks.
• Preview. Each item has an outcome: copy, apply, unchanged, keep_target, conflict or skipped, plus its fields and both sides' values. counts totals outcomes per item type, and fingerprint covers every version the apply depends on.
• Apply. The apply re-plans under the project lock. If the fingerprint no longer matches preview_fingerprint, it returns 409 BRANCH_PREVIEW_STALE with the new preview in details.preview. An import must choose use_source or use_target in choices for every conflict, otherwise 400 VALIDATION_ERROR with reason: "missing_choice".
• Merges never ask. A conflict keeps the target's version and becomes a decision. A task with an active claim on the target is never changed.
• Limits. A run takes at most 2,000 top-level items, 20,000 comments and messages, and 5 GiB of attachments (400 VALIDATION_ERROR, reason: "too_large"). The source and target must differ (reason: "same_branch"). Copied attachments count toward the project quota and need object storage.
• Events. A run emits one merge.import_applied or merge.merge_applied event on the target branch, plus decision.opened when it created decisions.
• Resolving. use_target keeps the target and records the source state as agreed. use_source applies the recorded source values if the target hasn't changed since; otherwise 409 BRANCH_DECISION_STALE with the refreshed decision in details.decision. use_source on a claimed task returns 409 TASK_ALREADY_CLAIMED, and a settled decision returns 409 CONFLICT with reason: "decision_closed".

A run has trigger dashboard or provider_merge, and a fork merge is recorded with status: "skipped" and skip_reason: "fork". A decision has reason changed_on_both, added_on_both, path_collision or target_claimed, and status open, resolved_source, resolved_target or superseded.

Branch errors

Existing codes gain these details.reason values:

Repository connections

A project can connect one repository. provider is github, gitlab or origin (Cursor Origin, hidden unless the server enables it). Set providers up first; see Git providers.

default_branch_mapping links the project's default branch to the provider's default branch D:

• { "mode": "rename_default" } (the default) renames the default branch to D. Another active branch named D is archived with reason replaced_on_connect; its work stays importable.
• { "mode": "use_existing", "branch_id": "…" } makes the active branch named D the default; the old default stays an ordinary branch.

create_existing_branches (default false) also creates branches for the provider's other branches; otherwise each one gets a branch on its first push.

Sync, re-enable, retry and disconnect return 404 NOT_FOUND when no repository is connected. A provider that doesn't answer gives 502 INTERNAL_ERROR, and lost provider access gives 409 REPOSITORY_AUTHORIZATION_INVALID. There is no reauthorization route: disconnect and connect again, and branches and their work are kept.

Organization Git integrations

Organization owners and admins can connect GitHub or GitLab once and import repositories as projects.

repository_selection is all or selected.

Webhooks and provider callbacks

Webhooks are verified on the raw body (up to 10 MiB) and stored for the sync worker; nothing changes until the worker applies them. They answer:

• 202 when the delivery is stored, is a duplicate, or is valid but for no connected repository (stored as ignored)
• 401 for a bad signature or timestamp
• 404 when the provider isn't configured, or the GitLab connection is unknown or disconnected
• 503 when the database is unavailable

See Architecture for how the worker applies deliveries.

Realtime

POST /api/v1/realtime/tickets   { "project_id": "…" }
  -> { "ticket": "…", "expires_at": "…" }
GET  ws://localhost:8801/api/v1/realtime/projects/<projectId>?ticket=<ticket>

• A ticket needs a session token and project membership. It is single-use, bound to one project, and valid for 45 seconds. Behind TLS, use wss://.
• The socket sends one envelope per event: project_id, branch_id (when the event has one), sequence, event_type, entity_type, entity_id, and actor. Chat events can add message_id, mentions and affected_participant.
• entity_type is one of chat, project, task, claim, agent, credential, session, document, hook, run, branch, merge, decision or repository.
• The socket is server-to-client only; a client message closes it. After a reconnect, read GET /api/v1/projects/:projectId/events with after set to the last sequence you saw.

Agent API

Every route in this section is under /api/v1/agent and needs an agent token. Paths below are relative to that prefix.

Agent sessions and events

• A session opens on branch_id, else the header's branch, else the default branch, and returns its branch_id. Opening one on an archived branch returns 409 BRANCH_ARCHIVED.
• A session is stale when its last heartbeat is more than 60 seconds old. Heartbeats and claims on a stale session return 409 AGENT_SESSION_STALE; closing is still allowed.
• Lifecycle event is session.started, session.ended or run.failed. The branch travels in X-Orchestrat-Branch-Id. session.started for a session that already exists on another branch returns 409 AGENT_SESSION_CLOSED with reason: "branch_mismatch". session.ended also closes the agent's other active sessions with the same external_session_id.

Agent tasks and claims

• Claims need an active session on the task's branch, a ready task and resolved dependencies. lease_seconds defaults to 300 and accepts 30–86,400. The response holds the claim and a claim_token; only the owning agent and session can release or complete it. Expired leases are reconciled when tasks are read or claimed. Concurrent claims produce one winner; the other gets 409 TASK_ALREADY_CLAIMED with the active claim's lease details.
• Updates take title, description, priority, status, optional acknowledged_through and required expected_version, applied as one version bump. A status change follows the human move rules and is refused with 409 TASK_NOT_CLAIMABLE while the task has an active claim: reason is own_claim when the caller holds it (use the claim routes instead), otherwise claimed. Moving to review or done applies the unread-comments guard.
• Bulk routes run in one transaction: any failure applies nothing and returns the single-item error with details.index and the item's task_id (update) or title (create). Results come back in input order, and each task emits the same events as the single route.

Agent documents and attachments

Bodies and rules match the human Documents routes. Attachment routes mirror the human Attachments routes under /documents/:documentId/attachments. Agents can't create folders.

Agent chats

Bodies match the human Chats routes.

Agent attention and handoffs

Agent branches

register refuses to revive a branch the provider deleted: when only archived branches have the name and the newest was deleted on the provider, it returns 409 BRANCH_ARCHIVED with branch_id and archived_at, and force_new: true creates a new branch anyway. git_default_branch is the checkout's origin/HEAD branch; it renames the default branch when that is still the fallback main, no repository is connected, and no active branch has the name. Creating more than 10 branches a minute per agent token returns 429 RATE_LIMITED; registering an existing branch is never limited.

Not implemented

The API has no routes for:

• deleting tasks, or editing and deleting comments
• remote MCP or MCP OAuth
• agent capability matching or auto-assignment
• syncing documents with a local filesystem, or collaborative cursors