paperclip/docs/api/agents.md

title, summary

title	summary
Agents	Agent lifecycle, configuration, keys, and heartbeat invocation

Manage AI agents (employees) within a company.

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.

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.

Org Chart

GET /api/companies/{companyId}/org

Returns the full organizational tree for the company.

Config Revisions

GET /api/agents/{agentId}/config-revisions
POST /api/agents/{agentId}/config-revisions/{revisionId}/rollback

View and roll back agent configuration changes.