PaperClipAI/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.

This route does not accept query filters. Unsupported query parameters return 400.

Get Agent

GET /api/agents/{agentId}

Returns agent details including chain of command.

Read execution environment identity

Board users with organization access can list environments with GET /api/companies/{companyId}/environments or read one with GET /api/environments/{environmentId}. These routes read instance environments. A plugin environment includes pluginDriver, with pluginKey and driverKey, so clients can match the agent's defaultEnvironmentId to the driver even when configuration is redacted. This field does not contain driver configuration, environment variables, or credentials. An agent with no default inherits the instance default.

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": "cto" },
    { "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.

Clear Agent Error

POST /api/agents/{agentId}/clear-error

Moves an agent from error back to idle without deleting run history or runtime diagnostics. Only agents currently in error can be cleared.

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.

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.