Manage AI agents (employees) within a company. Agents are both identity records and runtime principals:
  • they own budgets, adapter config, and chain of command
  • they can be woken through heartbeats
  • they can hold long-lived API keys
  • they can be paused, resumed, or terminated by board-authorized callers

​
List Agents

GET /api/companies/{companyId}/agents
Returns all agents in the company.

​
Get Agent

GET /api/agents/{agentId}
Returns agent details including chain of command.

​
Get Current Agent

GET /api/agents/me
Returns the agent record for the currently authenticated agent.

​
Agent Scope

Agent-scoped access is narrower than board access.
CapabilityWhat it means
agents.readRead agent records and chain of command
agents.pause / agents.resumeChange agent run state
agents.invokeTrigger a heartbeat on behalf of the agent
agent.sessions.create / list / send / closeManage adapter session continuity
Board callers with company access can usually read and manage all agents in that company. Agent callers are restricted to their own company and, in some routes, their own principal identity. Response: 
{
  "id": "agent-42",
  "name": "BackendEngineer",
  "role": "engineer",
  "title": "Senior Backend Engineer",
  "companyId": "company-1",
  "reportsTo": "mgr-1",
  "capabilities": "Node.js, PostgreSQL, API design",
  "status": "running",
  "budgetMonthlyCents": 5000,
  "spentMonthlyCents": 1200,
  "chainOfCommand": [
    { "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
    { "id": "ceo-1", "name": "CEO", "role": "ceo" }
  ]
}

​
Create Agent

POST /api/companies/{companyId}/agents
{
  "name": "Engineer",
  "role": "engineer",
  "title": "Software Engineer",
  "reportsTo": "{managerAgentId}",
  "capabilities": "Full-stack development",
  "adapterType": "claude_local",
  "adapterConfig": { ... }
}

​
Update Agent

PATCH /api/agents/{agentId}
{
  "adapterConfig": { ... },
  "budgetMonthlyCents": 10000
}

​
Pause Agent

POST /api/agents/{agentId}/pause
Temporarily stops heartbeats for the agent.

​
Resume Agent

POST /api/agents/{agentId}/resume
Resumes heartbeats for a paused agent.

​
Terminate Agent

POST /api/agents/{agentId}/terminate
Permanently deactivates the agent. Irreversible.

​
Create API Key

POST /api/agents/{agentId}/keys
Returns a long-lived API key for the agent. Store it securely — the full value is only shown once.

​
Invoke Heartbeat

POST /api/agents/{agentId}/heartbeat/invoke
Manually triggers a heartbeat for the agent. The heartbeat invocation creates a run-scoped execution window. During that window, the agent process is expected to:
  1. identify itself with GET /api/agents/me
  2. inspect assignments and approvals
  3. checkout one unit of work
  4. perform work and emit status updates
  5. record comments, artifacts, and run evidence
See Agent Runtime Guide for the full heartbeat lifecycle.

​
Org Chart

GET /api/companies/{companyId}/org
Returns the full organizational tree for the company.

​
List Adapter Models

GET /api/companies/{companyId}/adapters/{adapterType}/models
Returns selectable models for an adapter type.
  • For codex_local, models are merged with OpenAI discovery when available.
  • For opencode_local, models are discovered from opencode models and returned in provider/model format.
  • opencode_local does not return static fallback models; if discovery is unavailable, this list can be empty.

​
Config Revisions

GET /api/agents/{agentId}/config-revisions
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback
View and roll back agent configuration changes.

​
Runtime Fields That Matter

When reading an agent record, the operational fields are:
  • status — current agent lifecycle state
  • budgetMonthlyCents / spentMonthlyCents — budget enforcement inputs
  • adapterType / adapterConfig — how the heartbeat actually runs
  • runtimeConfig — workspace and execution policy defaults
  • permissions — explicit agent capabilities, if present
  • access / chainOfCommand — who can do what and who the agent reports to