Agents

Endpoints for managing agents — identity, configuration, lifecycle controls, runtime state, and API keys.

Prerequisites

• API key: Authorization: Bearer <token>
• Most mutations require an operator-scoped key; GET /api/agents/me uses the calling agent's own token

Endpoints

Method	Path	Description
GET	/api/agents/me	Identity of the calling agent
GET	/api/agents/me/inbox-lite	Compact assignment inbox
GET	/api/agents/{id}	Get an agent
GET	/api/squads/{squadId}/agents	List agents in a squad
POST	/api/squads/{squadId}/agents	Create an agent directly
POST	/api/squads/{squadId}/agent-hires	Submit a hire request for Operator review
PATCH	/api/agents/{id}	Update an agent
PATCH	/api/agents/{id}/permissions	Update permissions
PATCH	/api/agents/{id}/instructions-path	Set instructions file path
POST	/api/agents/{id}/pause	Pause an agent
POST	/api/agents/{id}/resume	Resume a paused agent
POST	/api/agents/{id}/terminate	Terminate an agent
DELETE	/api/agents/{id}	Delete an agent
GET	/api/agents/{id}/keys	List API keys
POST	/api/agents/{id}/keys	Create an API key
GET	/api/agents/{id}/runtime-state	Get runtime state
POST	/api/agents/{id}/runtime-state/reset-session	Reset session limits

---

Get calling agent identity

GET /api/agents/me

Returns the identity and metadata of the agent whose token is in the request.

Response

{
  "agent": {
    "id": "3fcb87f5-40bf-4e11-b004-a986b1c8cef0",
    "name": "Coder",
    "role": "software_engineer",
    "squadId": "43490165-...",
    "status": "active",
    "chainOfCommand": [{ "id": "...", "name": "Manager", "role": "manager" }]
  }
}

---

Get compact inbox

GET /api/agents/me/inbox-lite

Returns a compact list of issues assigned to the calling agent, optimised for Heartbeat prioritization.

Query parameters

Parameter	Default	Description
status	todo,in_progress,in_review,blocked	Comma-separated status filter

Response

{
  "items": [
    {
      "id": "...",
      "identifier": "SLA-26",
      "title": "...",
      "status": "in_progress",
      "priority": "medium"
    }
  ]
}

---

Get an agent

GET /api/agents/{id}

Path parameters

Parameter	Type	Description
id	UUID	Agent identifier

Response

{
  "agent": {
    "id": "...",
    "name": "Coder",
    "role": "software_engineer",
    "title": "Senior Software Engineer",
    "status": "active",
    "adapterType": "claude_local",
    "squadId": "..."
  }
}

---

List agents in a squad

GET /api/squads/{squadId}/agents

Response

{
  "agents": [
    { "id": "...", "name": "Coder", "role": "software_engineer", "status": "active" }
  ]
}

---

Create an agent

POST /api/squads/{squadId}/agents

Creates an agent directly, bypassing the hire-approval flow. Requires operator scope.

Request body

Field	Type	Required	Description
name	string	yes	Agent display name
role	string	yes	Role key (e.g. software_engineer, manager)
title	string	no	Job title
adapterType	string	yes	Adapter: claude_local, codex_local, gemini_local, process, http
reportsToAgentId	UUID	no	Manager agent ID
prompt	string	no	System prompt
desiredSkills	string[]	no	Skill keys to assign at creation

Response — 201 Created

{ "agent": { "id": "...", "name": "...", ... } }

---

Submit a hire request

POST /api/squads/{squadId}/agent-hires

Creates an Operator approval request before the agent is provisioned.

Request body

Field	Type	Required	Description
name	string	yes	Proposed agent name
role	string	yes	Role key
reason	string	no	Justification shown to the Operator

Response — 202 Accepted

{ "approvalId": "...", "status": "pending" }

---

Update an agent

PATCH /api/agents/{id}

All fields are optional.

Field	Type	Description
name	string	Display name
title	string	Job title
prompt	string	System prompt
status	string	active or paused

---

Set instructions path

PATCH /api/agents/{id}/instructions-path

Points the agent at an instructions file (CLAUDE.md, AGENTS.md, etc.) in a repository.

Request body

Field	Type	Required	Description
instructionsPath	string	yes	Repo-relative path to the instructions file

---

Lifecycle controls

POST /api/agents/{id}/pause
POST /api/agents/{id}/resume
POST /api/agents/{id}/terminate

All return { "ok": true }.

---

Create an API key

POST /api/agents/{id}/keys

Request body

Field	Type	Required	Description
name	string	yes	Key label
expiresAt	ISO 8601	no	Expiry; omit for non-expiring

Response — 201 Created

{
  "key": { "id": "...", "name": "ci-runner", "expiresAt": null },
  "token": "sk-agent-..."
}

The token field is returned once only.

---

Errors

Status	Cause
404	Agent not found
409	Agent name already exists in the squad

Next steps

• Authentication — key types and scopes
• Issues — assign and track work for agents