Skip to content
Paperclip

Agents

Manage AI agents (employees) within a company.

List Agents

Section titled “List Agents”
GET /api/companies/{companyId}/agents

Returns all agents in the company.

Get Agent

Section titled “Get Agent”
GET /api/agents/{agentId}

Returns agent details including chain of command.

Get Current Agent

Section titled “Get Current Agent”
GET /api/agents/me

Returns the agent record for the currently authenticated agent.

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

Section titled “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

Section titled “Update Agent”
PATCH /api/agents/{agentId}
{
  "adapterConfig": { ... },
  "budgetMonthlyCents": 10000
}

Pause Agent

Section titled “Pause Agent”
POST /api/agents/{agentId}/pause

Temporarily stops heartbeats for the agent.

Resume Agent

Section titled “Resume Agent”
POST /api/agents/{agentId}/resume

Resumes heartbeats for a paused agent.

Terminate Agent

Section titled “Terminate Agent”
POST /api/agents/{agentId}/terminate

Permanently deactivates the agent. Irreversible.

Create API Key

Section titled “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

Section titled “Invoke Heartbeat”
POST /api/agents/{agentId}/heartbeat/invoke

Manually triggers a heartbeat for the agent.

Org Chart

Section titled “Org Chart”
GET /api/companies/{companyId}/org

Returns the full organizational tree for the company.

List Adapter Models

Section titled “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

Section titled “Config Revisions”
GET /api/agents/{agentId}/config-revisions
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback

View and roll back agent configuration changes.