API reference

The Capy API gives programmatic access to the same platform the app uses: create threads, send messages, watch the agent work, and read what it produced. Endpoints evolve additively; nothing you integrate against changes shape.

A thread is a durable agent conversation on Capy's servers, with a VM attached for execution. Create one with an initial message, then read progress through its status and message transcript. Agents spawn subagents, which you observe read-only through /subagents. Earlier versions of the API called a subagent a task. The /tasks routes, with their taskId and taskPath fields, still work unchanged, so an integration built on them keeps running. Threads keep running after your request returns: you create work, then read progress.

Base URL⁠

Text
https://api.capy.ai/api/v1

Authentication⁠

Every request carries an API key as a bearer token:

Terminal
curl -H "Authorization: Bearer $CAPY_API_KEY" \
  "https://api.capy.ai/api/v1/threads?projectId=$PROJECT_ID"

Keys are organization-scoped and act as an explicit principal: you, or a service user your organization owns. Permissions and attribution follow that principal on every request. Mint keys in the app under Settings → API; the API never mints its own credentials. See Authentication for the principal model and when to use a service user.

Resources⁠

ResourceWhat you can do
ProjectsList the projects your key can access and read one, to resolve the projectId threads and automations take. List, set, and delete a project's shared environment variables; reads return names and descriptions, never values
ThreadsCreate (optionally attributed to a member via authorId), list, get, rename, archive/unarchive
MessagesRead the transcript, send, interrupt, cancel or expedite a queued message
FilesUpload files with POST /files, which returns a presigned upload URL per file, then attach them to a message by fileId
AttachmentsList the files attached to a thread's messages or delivered by its agent, and get a short-lived download URL for one
StreamsHold a Server-Sent Events connection on a thread or subagent: transcript entries as they commit plus the reply and tool activity of the turn in progress
SubagentsObserve a thread's subagent tree and each subagent's transcript, read-only. The same reads are also served at the original /tasks routes
FoldersList visible folders, page a folder's threads, file/unfile threads, pin/unpin (optionally for a member)
CaptainsList, create, and read Captains, and read a Captain's crew and digest
AutomationsCreate, inspect standing configuration, list by project, disable/enable, delete/restore
ReviewsStart a code review on a pull request, read a review round and its findings, configure per-repo review settings
Review rulesList, read, create, update, and delete your organization's review rules
Review filtersList, create, update, and delete review filter rules and ignored paths
UsageRead your organization's windowed spend and token totals, export them by hour or day per member, billing item, or thread with filters, and read the credit balance
UsersList your organization's active members to resolve a person to the id authorId and pin/unpin accept

Subagents are deliberately read-only: a subagent is driven through its thread. Send the thread a message and its agent redirects the work.

Pagination⁠

Most paged lists return { items, cursor }. A null cursor means you've reached the end. Otherwise, pass it back to get the next page. Bounded lists return everything as { items } with no cursor: projects, project environment variables, folders, users, Captains, and a Captain's crew.

The parameter that takes the cursor depends on the list:

  • Threads and automations take cursor, a transparent <epochMillis>:<resourceId> keyset token. The timestamp freezes the row's list position at mint time. Treat it as opaque and pass it back verbatim.
  • Subagents and a subagent's messages take after, set to the response's cursor.
  • A thread's messages and attachments page in both directions. The response carries cursor for newer entries and beforeCursor for older ones. Pass cursor as after to read forward, or beforeCursor as before to read backward. Without either parameter, you get the oldest page. A page can contain no items, so continue until the cursor for your direction is null.
  • A folder's threads take after with the response's cursor token, a <position>:<threadId> keyset over the folder's own order. Pass it back verbatim.
  • Review rules return { rules, nextCursor }. Pass nextCursor as cursor until it is null.
  • Review filters are unpaged: filter rules return { rules } and ignored paths return { ignorePaths }.

Errors⁠

Errors are tagged JSON objects: match on _tag, not on prose. The message fields are for humans and may change; the tags and status codes are the contract.

JSON
{
  "_tag": "capy/ThreadNotFound",
  "threadId": "jam_01..."
}

Two conventions:

  • Out of reach looks absent. A resource outside your organization's reach answers exactly like one that doesn't exist, so you can't probe for other tenants' ids. Most reads answer 404 for both. GET /review-rules/{id} answers 200 with { "rule": null } instead.
  • 401 is deliberately uniform. A missing, revoked, or expired key all answer the same capy/Unauthorized.

Rate limits⁠

Any operation can answer 429 with a retry-after header and a capy/RateLimited body:

JSON
{
  "_tag": "capy/RateLimited",
  "retryAfterSeconds": 5
}

The header and retryAfterSeconds carry the same number of seconds. Wait that long, then send the same request again. Open streams have their own limit, described in streaming.

Idempotency⁠

Thread creation takes a caller-minted requestId: retries of the same request converge on the same thread instead of starting a second billable run. Mint one id per logical create and reuse it across retries.

The full reference⁠

The generated endpoint pages in this section document every route, parameter, and schema, straight from the API contract, so they cannot drift from the server. The complete contract is also available as OpenAPI JSON. If you're coming from the Scout /api/v1, the migration guide maps every old route to its replacement.

OpenAPI specification

Inspect the complete machine-readable contract for client generation and validation.

Start with the quickstart to go from a key to a working thread in five curl commands, common flows for end-to-end sequences, or streaming to follow a thread over one connection instead of polling.

Open in Capy