The Company Agents REST API is how you script the orchestrator from outside. It is the same API the dashboard uses, so anything you can do in the UI you can do with curl. Use it for:
  • Automating company creation and teardown
  • Wiring Company Agents into an existing CI/CD pipeline
  • Building a custom dashboard or CLI
  • Pulling metrics into your observability stack
Do not use it to replace adapters. Adapters have a different contract (lease protocol, fencing tokens, MCP tool calls) and the REST API is the wrong layer for that.

​
Where the API lives

On a desktop install, the orchestrator serves the API at: 
http://localhost:3100
Note: the dashboard is on 3101; the API is on 3100. The two are separate ports so you can expose the API without exposing the dashboard or vice versa. On a Docker install, the API is on the orchestrator container: 
http://<host>:3100
In production, put a reverse proxy in front of it and terminate TLS. The orchestrator does not require TLS to start, but you should never run it on a network without TLS.

​
Versioning

All endpoints live under /v1/: 
GET /v1/companies
POST /v1/companies
GET /v1/companies/{id}/agents
The /v1/ prefix is a commitment: additive changes are allowed inside a version, breaking changes bump the version. Deprecations stay available for at least six months before removal.

​
Authentication

Every request needs an API token in the Authorization header: 
Authorization: Bearer ca_prod_<token>
Tokens are created at Dashboard → Settings → API Tokens or via the CLI: 
company-agents token create --name "ci-pipeline" --scopes "read,write"
The token is shown once on creation and never again. Store it in your secret manager. Rotate it with: 
company-agents token rotate <id>
See the authentication page for scopes, rotation, and revocation in detail.

​
Response shape

Every response is JSON with a consistent envelope: 
{
  "data": {...},
  "meta": {
    "requestId": "req_a1b2c3",
    "timestamp": "2026-04-11T10:42:17Z"
  }
}
List endpoints add pagination: 
{
  "data": [...],
  "meta": {
    "requestId": "req_a1b2c3",
    "timestamp": "2026-04-11T10:42:17Z",
    "page": { "size": 50, "cursor": "..." }
  }
}
Errors use the same envelope: 
{
  "error": {
    "code": "unauthorized",
    "message": "The provided token is not valid",
    "details": {...}
  },
  "meta": {...}
}

​
Your first request

curl -s http://localhost:3100/v1/companies \
  -H "Authorization: Bearer $CA_API_TOKEN" | jq
You should see a list of your companies. If the list is empty, create one: 
curl -s http://localhost:3100/v1/companies \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ampha Group",
    "slug": "ampha-group",
    "description": "Accounting firm in Sandton",
    "budget": { "usd": 500, "period": "monthly" }
  }' | jq
The response contains the new company’s ID. Every subsequent call (hiring agents, creating tasks, setting budgets) hangs off that ID.

​
Rate limits

The API has per-token rate limits:
  • Reads: 600 requests per minute
  • Writes: 120 requests per minute
  • Costly operations (exports, audit pulls, backups): 10 per minute
Exceeding a limit returns 429 with a Retry-After header. Back off and retry; do not hammer.

​
Webhooks

Every meaningful event can also be pushed to you via webhooks. Configure webhook endpoints at Dashboard → Settings → Webhooks and you get a POST for every task state change, approval request, budget breach, and audit event. Webhooks are the right choice when you want to react to events rather than poll. See the per-resource pages for which events each resource emits.

​
Per-resource pages

The rest of this section has a page per top-level resource:
  • Authentication — tokens, scopes, rotation
  • Companies — CRUD on companies
  • Agents — hire, pause, retire, update
  • Issues — tasks (called “issues” in the API for Paperclip compatibility), their state machine, and bulk operations
  • Approvals — list, approve, deny, comment
  • Goals and projects — the planning layer on top of tasks
  • Costs — cost roll-ups and exports
  • Secrets — read-only metadata on the encrypted store
  • Activity — activity log search and export
  • Dashboard — the read-only aggregated view the UI uses
Start with Authentication, then whatever resource you need.