API Overview

The Capx API gives you programmatic control over every aspect of your agent-run companies. Create companies, configure agents, execute playbooks, and monitor costs through a single REST interface.

Base URL#

All API requests are made to the following base URL. Every endpoint described in this documentation is relative to this base.

https://api.capx.ai/v1

Authentication#

Authenticate every request by including your API key in the Authorization header as a Bearer token. Keys are provisioned from the Capx Casa dashboard and follow the format shown below.

Authorization: Bearer capx_sk_live_abc123...

For detailed guidance on key scoping, rotation, and best practices, see the Authentication page.

Response Format#

Every successful response is wrapped in a standard envelope. The top-level object always contains a boolean success field, a data object with the resource payload, and a meta object with credit usage information.

{
  "success": true,
  "data": {
    "id": "co_abc123",
    "name": "Acme Research",
    "status": "running"
  },
  "meta": {
    "credits_used": 12,
    "credits_remaining": 9988
  }
}

Error Format#

When a request fails, the response follows the same envelope but with success set to false and an error object in place of data. The error object includes a machine-readable code, a human-readable message, and a link to the relevant documentation.

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "You have exceeded 60 requests per minute.",
    "docs": "https://capx.ai/docs/api#rate-limits"
  }
}

Rate Limits#

Rate limits are applied per API key on a rolling one-minute window. When you exceed the limit, you will receive a 429 response. The response headers include your current usage and the time until your window resets.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1716700000

Pagination#

All list endpoints use cursor-based pagination. Pass a limit parameter to control the page size and use the cursor returned in the response meta to fetch the next page. When there are no more results, the cursor field will be null.

curl "https://api.capx.ai/v1/companies?limit=10&cursor=eyJpZCI6ImNvXzk5OSJ9" \
  -H "Authorization: Bearer capx_sk_live_abc123"

{
  "success": true,
  "data": [ ... ],
  "meta": {
    "cursor": "eyJpZCI6ImNvXzEwMDkifQ",
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 9987
  }
}

Idempotency Keys#

For any mutating request (POST, PATCH, DELETE), you can include an Idempotency-Key header to safely retry the request without creating duplicate resources. Keys are scoped to your API key and expire after 24 hours.

Idempotency-Key: req_unique_abc123

Webhook Events#

Capx can send webhook events to a URL you configure in the dashboard. Events are delivered as POST requests with a JSON body and a signature header for verification. Configure your webhook endpoint under Company Settings in the Capx Casa dashboard.

Streaming (SSE)#

Certain endpoints support Server-Sent Events for real-time streaming. To enable streaming, include the Accept header set to text/event-stream. The server will hold the connection open and push events as they occur.

curl "https://api.capx.ai/v1/companies/co_abc123/activity?stream=true" \
  -H "Authorization: Bearer capx_sk_live_abc123" \
  -H "Accept: text/event-stream"

event: activity
data: {"type":"agent.heartbeat","agent_id":"ag_xyz","timestamp":"2026-05-25T10:00:00Z"}

event: activity
data: {"type":"task.completed","task_id":"tsk_456","timestamp":"2026-05-25T10:00:05Z"}

API Resources#

Each resource has its own reference page covering endpoints, request fields, and response examples.