Agents API

All agent endpoints. Agents belong to a workspace and represent a running Claude Code session.

Create agent

POST /api/workspaces/:id/agents

Creates and starts a new agent in the specified workspace.

Request body:

Field	Type	Required	Description
role	string	yes	Agent role (e.g. "code", "review")
task	string	no	Initial task message. Falls back to role template default
bypass	boolean	no	Skip permission prompts (default false)
spawnedBy	string	no	ID of the agent that requested this spawn
allowDuplicate	boolean	no	Allow multiple agents with the same role (default false)

Response: 201 with the created AgentSession object.

Returns 409 if a duplicate role already exists and allowDuplicate is false.

---

Send message

POST /api/agents/:id/send

Sends a follow-up message to a running agent.

Request body:

Field	Type	Required	Description
message	string	conditional	Text message (required if no attachments)
attachments	AttachmentData[]	no	File attachments (image or document)
effort	string	no	Override effort level for this turn
model	string	no	Override model for this turn

Response: 200 { ok: true, agentId: string }

---

Stop agent

POST /api/agents/:id/stop

Interrupts a running agent. Aborts the SDK conversation, drains pending delegation queues, and sets status to idle.

Response: 200 { ok: true }

---

Compact context

POST /api/agents/:id/compact

Triggers SDK context compaction for the agent. Fails with 409 if the agent is currently working.

Response: 200 { ok: true }

---

Send slash command

POST /api/agents/:id/command

Sends a slash command to the agent (e.g. /compact, /clear).

Request body:

Field	Type	Required	Description
command	string	yes	Slash command starting with /

Response: 200 { ok: true }

Fails with 409 if the agent is busy.

---

Reopen agent

POST /api/agents/:id/reopen

Reopens a closed (history) agent, moving it back to the active list.

Response: 200 with the AgentSession object.

---

Update agent

PATCH /api/agents/:id

Updates agent configuration fields.

Request body (all optional):

Field	Type	Description
customName	string	Display name override
model	string	Model override
effort	string	Effort level: "low", "medium", or "high"
bypass	boolean	Permission bypass
cleanMode	boolean	Show only agent/user messages in UI
isOrchestrator	boolean	Enable orchestrator capabilities
canSpawnSubagents	boolean	Allow SDK Agent tool usage

Response: 200 with the updated AgentSession.

---

Delete agent

DELETE /api/agents/:id

Closes the agent and moves it to history.

Response: 200 { ok: true }

---

Get agent log (paginated)

GET /api/agents/:id/log?limit=50&offset=0

Returns paginated log entries for the agent. Entries are returned in chronological order, newest at the end.

Query parameters:

Param	Default	Description
limit	50	Number of entries to return
offset	0	Offset from the end of the log

Response:

{
  "total": 120,
  "limit": 50,
  "offset": 0,
  "entries": [ ... ]
}

---

Delegate task

POST /api/agents/delegate

Delegates a task from an orchestrator agent to another agent by role. Only orchestrator agents can delegate.

Request body:

Field	Type	Required	Description
from	string	yes	Orchestrator agent ID
to	string	yes	Target role name
toId	string	no	Specific target agent ID
task	string	yes	Task description
model	string	no	Model override for the target agent

Response: 200 with delegation result. Returns 403 if the source agent is not an orchestrator.

---

Get agent pool

GET /api/agents/pool?workspaceId=xxx

Returns all active agents with sessions, optionally filtered by workspace.

Query parameters:

Param	Required	Description
workspaceId	no	Filter by workspace

Response:

[
  {
    "id": "abc123",
    "role": "code",
    "status": "idle",
    "currentTask": "...",
    "workspaceId": "ws1",
    "queueSize": 0
  }
]

---

Create spawn request

POST /api/agents/spawn-request

Requests spawning multiple agents. Requires user approval via the UI.

Request body:

Field	Type	Required	Description
fromAgentId	string	yes	Requesting agent ID
roles	string[]	yes	Roles to spawn
tasks	string[]	yes	Task for each role
reason	string	no	Reason for the request

Response: 201 { requestId: string }

---

Respond to spawn request

POST /api/agents/spawn-request/:id/respond

Approves or denies a pending spawn request.

Request body:

Field	Type	Required	Description
approved	boolean	yes	Whether to approve
maxCount	number	no	Max agents to spawn
approvedRoles	string[]	no	Subset of roles to approve

Response: 200 { ok: true, status, maxCount, approvedRoles }