Agents

Agents

Manage agents inside a company.

Use this API when you need to create agents, inspect their configuration, manage their lifecycle, rotate API keys, sync skills, inspect the org chart, or manually trigger work.

Quick Rules

This API is company-scoped. Every meaningful request is tied to a company. Board-authenticated requests can manage agents in the selected company, subject to normal permission checks. Agent-authenticated requests can only act inside their own company. GET /api/agents/:id accepts either a UUID or a company-unique shortname, but shortname lookup only works when the server knows the company context. In practice that means ?companyId=... or agent auth. Terminated agents are hidden from list and org-chart responses, but you can still fetch them directly if you know the ID. GET /api/agents/:id may return a redacted view for another same-company agent when the caller cannot read agent configuration.

---

Common Fields

The agent payload is a normal JSON object. These are the fields you will see most often:

| Field | Meaning | |---|---| | name | Human-friendly name. The server also derives a company-unique URL key from it. | | role | Role label such as ceo, engineer, or general. | | title | Optional display title. | | reportsTo | Parent agent in the org tree. Must be in the same company and cannot create a cycle. | | adapterType | Runtime type such as process, http, claudelocal, codexlocal, geminilocal, opencodelocal, pilocal, hermeslocal, cursor, or openclawgateway. External adapters can also be registered. | | adapterConfig | Adapter-specific config. Secret references are allowed inside env. | | runtimeConfig | Runtime settings. heartbeat.enabled defaults to false when you create an agent. | | budgetMonthlyCents | Monthly budget in cents. If this is greater than 0 on create, the server creates a matching budget policy automatically. | | status | Lifecycle state. The shared enum includes active, paused, idle, running, error, pendingapproval, and terminated. | | permissions | Agent-level permissions, currently canCreateAgents. |

---