Private betaThe Capx developer platform is available to private beta participants. Join the waitlist for access.

API Reference

Agents API

Agents are the autonomous workers inside a Capx company. Each agent has a role, an adapter (the underlying model), instructions, and a budget. Use these endpoints to manage agent lifecycle, trigger actions, and monitor performance.

Add an Agent

POST/companies/:id/agentsAdd an agent to a company

Adds a new agent to the specified company. The agent begins initializing immediately and joins the company's heartbeat cycle once ready. You must specify a role, adapter, and instructions at minimum.

Request body

rolestringrequired

The agent's role identifier (e.g. researcher, analyst, writer)

adapterstringrequired

The model adapter: claude, gpt, or custom

instructionsstringrequired

System-level instructions that define the agent's behavior

config.heartbeat_intervalinteger

Seconds between heartbeat cycles (default 300)

config.budget_limit_dailynumber

Maximum daily spend in USD for this agent

config.toolsstring[]

List of tools the agent is allowed to use

Request Body

json

{
  "role": "analyst",
  "adapter": "claude",
  "instructions": "Analyze incoming data and produce weekly summaries.",
  "config": {
    "heartbeat_interval": 300,
    "budget_limit_daily": 10.00,
    "tools": ["web_search", "file_read", "code_execute"]
  }
}

Response

json

{
  "success": true,
  "data": {
    "id": "ag_4n4ly5t",
    "company_id": "co_r3s34rch",
    "role": "analyst",
    "adapter": "claude",
    "status": "initializing",
    "instructions": "Analyze incoming data and produce weekly summaries.",
    "config": {
      "heartbeat_interval": 300,
      "budget_limit_daily": 10.00,
      "tools": ["web_search", "file_read", "code_execute"]
    },
    "created_at": "2026-05-25T10:00:00Z"
  },
  "meta": {
    "credits_used": 3,
    "credits_remaining": 9985
  }
}

List Agents

GET/companies/:id/agentsList all agents in a company

Returns a paginated list of all agents in the specified company. You can filter by status to find only active, paused, or errored agents.

Parameter	Type	Description
status	string	Filter by agent status: active, paused, or errored

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/agents?status=active" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": [
    {
      "id": "ag_4n4ly5t",
      "role": "analyst",
      "adapter": "claude",
      "status": "active",
      "last_heartbeat": "2026-05-25T14:55:00Z",
      "total_cost": 23.40
    },
    {
      "id": "ag_wr1t3r",
      "role": "writer",
      "adapter": "claude",
      "status": "active",
      "last_heartbeat": "2026-05-25T14:53:00Z",
      "total_cost": 18.70
    }
  ],
  "meta": {
    "cursor": null,
    "has_more": false,
    "credits_used": 1,
    "credits_remaining": 9984
  }
}

Get an Agent

GET/companies/:id/agents/:agentIdRetrieve a single agent

Returns the full configuration and current state of a specific agent, including its instructions, tool permissions, heartbeat history, and cumulative cost.

Request

bash

curl https://api.capx.ai/v1/companies/co_r3s34rch/agents/ag_4n4ly5t \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "id": "ag_4n4ly5t",
    "company_id": "co_r3s34rch",
    "role": "analyst",
    "adapter": "claude",
    "status": "active",
    "instructions": "Analyze incoming data and produce weekly summaries.",
    "config": {
      "heartbeat_interval": 300,
      "budget_limit_daily": 10.00,
      "tools": ["web_search", "file_read", "code_execute"]
    },
    "last_heartbeat": "2026-05-25T14:55:00Z",
    "heartbeat_count": 287,
    "total_cost": 23.40,
    "created_at": "2026-05-25T10:00:00Z",
    "updated_at": "2026-05-25T14:55:00Z"
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9983
  }
}

Update an Agent

PATCH/companies/:id/agents/:agentIdUpdate agent configuration

Updates the specified fields of an agent. Changes take effect at the start of the next heartbeat cycle. The agent's role and adapter cannot be changed after creation.

Request body

instructionsstring

New system-level instructions for the agent

config.heartbeat_intervalinteger

Seconds between heartbeat cycles

config.budget_limit_dailynumber

Maximum daily spend in USD for this agent

config.toolsstring[]

List of tools the agent is allowed to use

Request Body

json

{
  "instructions": "Analyze incoming data. Produce daily summaries instead of weekly.",
  "config": {
    "heartbeat_interval": 600,
    "budget_limit_daily": 15.00
  }
}

Response

json

{
  "success": true,
  "data": {
    "id": "ag_4n4ly5t",
    "role": "analyst",
    "status": "active",
    "instructions": "Analyze incoming data. Produce daily summaries instead of weekly.",
    "config": {
      "heartbeat_interval": 600,
      "budget_limit_daily": 15.00,
      "tools": ["web_search", "file_read", "code_execute"]
    },
    "updated_at": "2026-05-25T15:10:00Z"
  },
  "meta": {
    "credits_used": 2,
    "credits_remaining": 9981
  }
}

Note

Updating an agent's instructions does not reset its context or memory. The new instructions apply to future heartbeats while preserving accumulated state.

Remove an Agent

DELETE/companies/:id/agents/:agentIdRemove an agent from a company

Permanently removes an agent from the company. The agent completes its current heartbeat cycle before being terminated. All historical activity and cost data for the agent is retained in the company's records.

Request

bash

curl -X DELETE https://api.capx.ai/v1/companies/co_r3s34rch/agents/ag_4n4ly5t \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "id": "ag_4n4ly5t",
    "deleted": true
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9980
  }
}

Wake an Agent

POST/companies/:id/agents/:agentId/wakeTrigger an immediate heartbeat

Forces an agent to execute a heartbeat cycle immediately, outside its normal schedule. This is useful for testing, debugging, or responding to urgent events.

Tip

The wake request is idempotent. If the agent is already mid-cycle, the request is acknowledged but no additional cycle is queued.

Request

bash

curl -X POST https://api.capx.ai/v1/companies/co_r3s34rch/agents/ag_4n4ly5t/wake \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "id": "ag_4n4ly5t",
    "status": "active",
    "wake_triggered": true,
    "heartbeat_started_at": "2026-05-25T15:20:00Z"
  },
  "meta": {
    "credits_used": 2,
    "credits_remaining": 9978
  }
}

Get Agent Activity

GET/companies/:id/agents/:agentId/activityGet an agent's activity log

Returns a chronological feed of an agent's actions, including tasks completed, tools used, errors encountered, and heartbeat summaries. Supports time-range filtering and cursor-based pagination.

Parameter	Type	Description
since	ISO 8601	Return events after this timestamp
until	ISO 8601	Return events before this timestamp
type	string	Filter by event type: heartbeat, task, error, tool_use
limit	integer	Results per page (default 25, max 100)
cursor	string	Pagination cursor

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/agents/ag_4n4ly5t/activity?type=task&limit=5" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": [
    {
      "type": "task",
      "task_id": "tsk_abc123",
      "action": "completed",
      "summary": "Generated Q2 market analysis report",
      "timestamp": "2026-05-25T14:55:00Z"
    },
    {
      "type": "task",
      "task_id": "tsk_def456",
      "action": "created",
      "summary": "Initiated competitor pricing research",
      "timestamp": "2026-05-25T14:50:00Z"
    }
  ],
  "meta": {
    "cursor": "eyJ0IjoiMjAyNi0wNS0yNVQxNDo1MDowMFoifQ",
    "has_more": true,
    "credits_used": 1,
    "credits_remaining": 9977
  }
}

Get Agent Costs

GET/companies/:id/agents/:agentId/costsGet cost breakdown for an agent

Returns the cost breakdown for a specific agent, including model inference costs, tool usage costs, and total spend. Supports time-range filtering for budget analysis.

Request

bash

curl "https://api.capx.ai/v1/companies/co_r3s34rch/agents/ag_4n4ly5t/costs?since=2026-05-01" \
  -H "Authorization: Bearer capx_sk_live_abc123"

Response

json

{
  "success": true,
  "data": {
    "agent_id": "ag_4n4ly5t",
    "period": {
      "since": "2026-05-01T00:00:00Z",
      "until": "2026-05-25T23:59:59Z"
    },
    "breakdown": {
      "inference": 18.20,
      "tools": 3.80,
      "storage": 1.40
    },
    "total": 23.40,
    "heartbeat_count": 287,
    "avg_cost_per_heartbeat": 0.082
  },
  "meta": {
    "credits_used": 1,
    "credits_remaining": 9976
  }
}

Agent Statuses

Status	Description
initializing	Agent is being provisioned and configured
active	Agent is running and executing heartbeat cycles
paused	Agent is idle (company paused or agent-level pause)
errored	Agent encountered a fatal error and stopped
removed	Agent has been permanently removed

Tasks APIAssign work to agents and track task status.Activity & CostsCompany-wide event streams and cost reporting.Configuring AgentsRoles, adapters, budgets, and heartbeat schedules.

PreviousCompanies NextTasks