API reference — Capybari

Not generally available Public API v1 — with stable versioning, published rate limits, scoped tokens and outbound webhooks — is planned for Q4 2026. Until then these endpoints exist to serve the web application. They are undocumented in the product, unversioned, and will change without notice. If you build on them now, assume you are maintaining that integration yourself.

Building something anyway? Tell us what you are trying to do. Several endpoints on the v1 list are there because somebody asked. Get in touch.

Authentication

Every request carries a bearer token

Tokens are issued per user and inherit that user's access. Scoped machine tokens with per-project permissions are part of the v1 work.

Bearer token — sent in the Authorization header; never in a query string.
Ownership enforced server-side — a token cannot read a project it does not own, regardless of the id you pass.
JSON in, JSON out — application/json throughout. Errors carry a machine-readable code and a human-readable message.
HTTPS only — plain HTTP requests are refused rather than redirected.

Authentication

curl https://app.capybari.com/api/projects \
  -H "Authorization: Bearer cby_live_••••••••" \
  -H "Accept: application/json"

Error shape

{
  "error": {
    "code": "request_not_found",
    "message": "No request with that id in this project.",
    "status": 404
  }
}

Requests

Filing work and reading the plan

A request is the unit you create. Everything else — the plan, the tasks, the runs, the deployment — descends from it.

POST /api/requests

{
  "project_id": "8f3c1a2e-...",
  "title": "Card payments fail for European customers",
  "description": "Checkout returns a 402 for cards issued in the EEA.",
  "request_type": "bug",
  "priority": "high",
  "auto_start": true
}

GET /api/requests/{id}

{
  "id": "b71e4d09-...",
  "request_number": 142,
  "title": "Add strong customer authentication to checkout",
  "status": "in_progress",
  "priority": "high",
  "plan_summary": "Six tasks across architecture, database, security review,
                   backend, frontend and QA. T-03 holds a review gate.",
  "planned_tasks": [
    { "code": "T-01", "role": "architect",
      "title": "Assess checkout against SCA rules", "depends_on": [] },
    { "code": "T-02", "role": "database-engineer",
      "title": "Migration for authentication outcomes", "depends_on": ["T-01"] },
    { "code": "T-03", "role": "security-engineer",
      "title": "Threat review of the payment flow",
      "depends_on": ["T-01"], "requires_review": true }
  ],
  "approved_at": "2026-07-14T09:02:11Z",
  "deployed_at": null
}

Runs

Watching a task work

Runs stream over Server-Sent Events. This is how the board shows you commands and output as they happen rather than after the fact.

GET /api/runs/{id}/events (SSE)

event: command
data: {"at":"14:22:08","role":"backend-developer",
       "text":"git worktree add .worktrees/t-04 task/t-04-sca-challenge"}

event: output
data: {"at":"14:26:20","role":"backend-developer",
       "text":"pytest tests/payments — 84 passed in 11.4s"}

event: report
data: {"at":"14:27:02","task":"T-04","status":"completed",
       "report":{"summary":"Added the 3-D Secure challenge step.",
                 "files_modified":3,"risks":1,"blockers":0}}

event: done
data: {"status":"completed"}

GET /api/tasks/{id}

{
  "task_code": "T-04",
  "title": "Implement 3-D Secure challenge step",
  "status": "completed",
  "branch_name": "task/t-04-sca-challenge",
  "worktree_path": ".worktrees/t-04",
  "depends_on": ["T-02", "T-03"],
  "completion_report": {
    "summary": "Added the 3-D Secure challenge step to the card payment path.",
    "files_modified": [
      "app/payments/challenge.py — new challenge handler",
      "app/payments/gateway.py — route into challenge"
    ],
    "risks": ["Wallet payments untested against the live sandbox"],
    "assumptions": [],
    "recommendations": ["Run T-06 before deploying to production"],
    "blockers": []
  }
}

Deployment and investigations

Shipping it, and what happens when it breaks

POST /api/deployment-targets/{id}/runs

{
  "request_id": "b71e4d09-...",
  "phase": "merge"
}

→ 202 Accepted
{
  "id": "3c9a7f11-...",
  "status": "running",
  "phase": "merge",
  "rollback_armed": true
}

GET /api/investigations/{id}

{
  "id": "1a4e9c07-...",
  "reference": "INV-11",
  "status": "resolved",
  "access_level": "read_only",
  "triggered_by_deployment_run_id": "3c9a7f11-...",
  "summary": "SCA_PROVIDER_KEY was not set on the production host, so the
              challenge handler raised on import and /healthz returned 503.",
  "resolution": "Opened REQ-143 to add the variable to the deploy configuration.",
  "created_request_id": "c02b8e55-...",
  "resolved_at": "2026-07-14T09:18:15Z"
}

Surface

Endpoints

What exists today, and what v1 will add. Nothing here is stable until v1.

Endpoint	Method	Purpose	Status
`/api/projects`	GET, POST	List and create projects	Internal
`/api/projects/{id}/repos`	GET, POST	Connected repositories	Internal
`/api/requests`	GET, POST	File and list requests	Internal
`/api/requests/{id}`	GET, PATCH	Read a request and its plan	Internal
`/api/requests/{id}/approve`	POST	Approve a plan and dispatch work	Internal
`/api/tasks/{id}`	GET	Task detail and completion report	Internal
`/api/tasks/{id}/respond`	POST	Answer a question from an agent	Internal
`/api/runs/{id}/events`	GET (SSE)	Live run stream	Internal
`/api/deployment-targets`	GET, POST	Configure targets	Internal
`/api/deployment-targets/{id}/runs`	POST	Trigger a deployment	Internal
`/api/investigations`	GET	List and read investigations	Internal
`/api/agent-profiles`	GET, POST	Project team members	Internal
`/api/role-contracts`	GET, PUT	Read and edit role contracts	Internal
`/api/webhooks`	—	Outbound event delivery	Planned · Q4 2026
`/api/tokens`	—	Scoped machine tokens	Planned · Q4 2026

"Internal" means it powers the application and may change without notice. Do not build against it.

Planned

Webhook events

The event set we intend to ship with v1. Names are not final.

Event	Fires when	Most useful for
`request.planned`	The manager finishes planning	Notifying an approver
`request.approved`	A plan is approved	Kicking off external tracking
`task.review_required`	A review gate stops work	Paging the right human
`task.input_required`	An agent asks a question	Getting an answer quickly
`task.completed`	A task finishes and reports	Pulling the structured report
`deployment.succeeded`	A health check passes	Release announcements
`deployment.rolled_back`	A health check fails and rollback runs	Incident channels
`investigation.opened`	An investigation starts	On-call routing
`investigation.resolved`	A cause is written up	Postmortem tooling

Objects

The nouns you will be working with

Project

Owns repositories, a team of agent profiles, deployment targets and an autonomy level. The unit of isolation between clients or products.

Request

What you file. Typed, prioritised, orderable on the board. Carries a plan summary and the planned task list once the manager has read it.

Task

One unit of work for one specialist, on its own branch in its own worktree. Declares depends_on, may hold a review gate, and ends in a structured completion report.

Run

One execution of one task. Streams events. A task can have several runs if it is retried or continued after answering a question.

Agent profile

A role on a project team: system prompt, rules, model and effort defaults, permission mode, and whether it requires human review.

Deployment target

An SSH host with a deploy path, a deploy command, a health check, a diagnostics command and a rollback command.

Deployment run

One attempt to ship. Records its phase, merge summary, deploy output, health-check output and — if it came to it — rollback output.

Investigation

Opened when something fails in production. Carries an access level (read_only by default), a summary, a resolution, and optionally the request it opened to fix things.

Questions

About the API

Can I use these endpoints now?

You can call them, and they will work. They are also unversioned and undocumented in the product, and we will change them without telling you. That is an honest description of an internal interface, not a warning we expect you to ignore.

When is v1 actually coming?

Q4 2026 is the intention on the roadmap. We publish quarters, not dates, and we do not commit contractually to either.

Will v1 break what is here today?

Almost certainly, in places. v1 adds scoped tokens, stable versioning under a /v1/ prefix, published rate limits and webhooks. The object shapes above are the ones most likely to survive largely intact.

Is there an SDK?

No, and there will not be one before v1. A client library wrapping an unstable interface is worse than no client library.

How do I get notified about changes?

Everything that ships lands on the changelog, and the monthly community update covers anything that would break an integration.

Tell us what you would build

The v1 surface is still being decided. If you have a concrete integration in mind, now is the moment it can still change the shape of it.

Get in touch Read the docs

The API, before it is an API

Every request carries a bearer token

Filing work and reading the plan

Watching a task work

Shipping it, and what happens when it breaks

Endpoints

Webhook events

The nouns you will be working with

About the API

Tell us what you would build