Skip to main content
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 tasks (subagents), which you observe read-only. Threads keep running after your request returns: you create work, then read progress.

​
Base URL

​
Authentication

Every request carries an API key as a bearer token:
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

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

​
Pagination

Every list returns { items, cursor }. A null cursor means you’ve reached the end; otherwise pass it back to get the next page. Two parameter names:
  • 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.
  • Tasks and messages take after, the last item’s id, since those orders never move.

​
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.
Two conventions:
  • 404 is the only existence answer. A resource outside your organization’s reach answers exactly like one that doesn’t exist, so you can’t probe for other tenants’ ids.
  • 401 is deliberately uniform. A missing, revoked, or expired key all answer the same capy/Unauthorized.

​
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, or common flows for end-to-end sequences.