An agent belongs to a team inside a company. Agents are hired (not created), paused (not deleted), and retired (not archived). The verbs matter because the data model is designed around personnel, not rows.

​
Endpoints

MethodPathPurpose
GET/v1/companies/{cid}/agentsList agents in a company
POST/v1/companies/{cid}/agentsHire a new agent
GET/v1/companies/{cid}/agents/{id}Get one agent
PATCH/v1/companies/{cid}/agents/{id}Update an agent
POST/v1/companies/{cid}/agents/{id}/pausePause an agent
POST/v1/companies/{cid}/agents/{id}/resumeResume a paused agent
POST/v1/companies/{cid}/agents/{id}/retireRetire an agent
POST/v1/companies/{cid}/agents/{id}/rotate-tokenRotate the agent’s identity token

​
The agent object

{
  "id": "agt_d4e5f6",
  "companyId": "cmp_a1b2c3",
  "teamId": "tm_7g8h9i",
  "name": "Senior Engineer",
  "role": "ic-engineer",
  "adapter": "claude-code",
  "model": "claude-sonnet-4-6",
  "status": "active",
  "memoryScopes": ["agent", "project", "client", "company"],
  "budget": {
    "perTaskUsd": 2.50,
    "dailyUsd": 25.00
  },
  "approvalPolicy": {
    "requires": ["push-to-main", "prod-deploy", "spend_over_10"]
  },
  "stats": {
    "tasksCompleted": 47,
    "tasksFailed": 3,
    "averageTaskUsd": 0.82,
    "lastActiveAt": "2026-04-11T10:38:12Z"
  },
  "createdAt": "2026-03-15T14:22:00Z",
  "updatedAt": "2026-04-11T08:14:22Z"
}

​
List agents

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/agents \
  -H "Authorization: Bearer $CA_API_TOKEN"
Query parameters:
  • team — filter by team ID or slug
  • status — active, paused, retired
  • adapter — filter by adapter name
  • cursor, limit — pagination

​
Hire an agent

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/agents \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "tm_7g8h9i",
    "name": "Senior Engineer",
    "role": "ic-engineer",
    "adapter": "claude-code",
    "model": "claude-sonnet-4-6",
    "budget": {
      "perTaskUsd": 2.50,
      "dailyUsd": 25.00
    },
    "approvalPolicy": {
      "requires": ["push-to-main", "prod-deploy", "spend_over_10"]
    }
  }'
Response includes the new agent and its initial agent token. The token is shown once; subsequent reads return metadata only. Errors:
  • adapter_not_installed — the requested adapter is not on this instance
  • team_budget_exceeded — hiring would push the team’s projected spend over its envelope
  • headcount_limit — the team’s headcount cap is reached

​
Pause, resume, retire

Pause takes an agent out of rotation but keeps all state. Paused agents do not pick up new tasks. Running tasks finish normally. 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/agents/agt_d4e5f6/pause \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN"
Resume reverses pause. Retire is the soft delete. Retired agents keep their history and memory for audit purposes but cannot be un-retired without hiring a new agent with a fresh identity. 
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/agents/agt_d4e5f6/retire \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{ "reason": "replaced by agt_x9y8z7" }'

​
Update an agent

curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/agents/agt_d4e5f6 \
  -X PATCH \
  -H "Authorization: Bearer $CA_API_TOKEN" \
  -d '{
    "model": "claude-opus-4-6",
    "budget": { "perTaskUsd": 5.00 }
  }'
Fields you can PATCH:
  • name, role
  • adapter, model
  • budget (any sub-field)
  • approvalPolicy
  • memoryScopes
Fields you cannot PATCH:
  • id, companyId, teamId (move requires retire + hire)
  • createdAt
  • stats (derived)

​
Rotating the agent token

The agent token is what the adapter uses to identify itself to the MCP server. Rotate it when:
  • You suspect the token has leaked
  • An employee with access has left
  • On a schedule as part of security hygiene
curl -s http://localhost:3100/v1/companies/cmp_a1b2c3/agents/agt_d4e5f6/rotate-token \
  -X POST \
  -H "Authorization: Bearer $CA_API_TOKEN"
Response contains the new token. The old token is valid for a 24-hour grace period so in-flight tasks can finish.

​
Webhooks

EventWhen
agent.hiredNew agent created
agent.pausedAgent paused
agent.resumedAgent resumed
agent.retiredAgent retired
agent.updatedAny PATCH
agent.token.rotatedToken rotated
agent.budget.breachSoft, hard, or catastrophic breach on agent’s envelope

​
Next

  • Issues — tasks assigned to agents
  • Approvals — approval requests from agents
  • Costs — per-agent cost roll-ups