Agents API

Core REST API endpoints for agent lifecycle management, configuration, files, and metadata. All endpoints require JWT Bearer token unless noted. See Authentication for details.

Full request/response schemas available at http://localhost:8000/docs when running locally (Swagger UI).

Authentication

# All requests require a Bearer token
curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents

Agent CRUD and Lifecycle

Endpoint	Method	Description
/api/agents	GET	List all agents
/api/agents	POST	Create agent
/api/agents/{name}	GET	Get agent details
/api/agents/{name}	DELETE	Delete agent
/api/agents/{name}/start	POST	Start container
/api/agents/{name}/stop	POST	Stop container
/api/agents/{name}/rename	PUT	Rename agent

GET

/api/agents

List all agents accessible to the current user. Supports filtering by tags.

Name	Type	Required	Description
tags	string	No	Comma-separated tag filter (OR logic), e.g. ?tags=prod,staging

curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents

# Response
[
  {
    "name": "research-agent",
    "type": "business-assistant",
    "status": "running",
    "port": 2222,
    "created": "2026-01-15T10:30:00Z",
    "runtime": "claude-code",
    "tags": ["research", "prod"]
  }
]

POST

/api/agents

Create a new agent. The agent will be deployed as an isolated Docker container.

Name	Type	Required	Description
name	string	Yes	Unique agent name
type	string	No	Agent type (default: "business-assistant")
template	string	No	Template to initialize from
runtime	string	No	"claude-code" or "gemini-cli"
runtime_model	string	No	Model override (e.g. "sonnet-4.5")
resources	object	No	{"cpu": "2", "memory": "4g"}
custom_instructions	string	No	Custom system prompt
github_repo	string	No	GitHub repo (e.g. "Org/repo")

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-agent",
    "template": "business-assistant",
    "runtime": "claude-code",
    "resources": {"cpu": "2", "memory": "4g"}
  }' \
  http://localhost:8000/api/agents

# Response: AgentStatus
{
  "name": "research-agent",
  "type": "business-assistant",
  "status": "running",
  "port": 2222,
  "created": "2026-03-26T12:00:00Z",
  "runtime": "claude-code"
}

GET

/api/agents/:name

Get details of a specific agent including ownership, sharing, and autonomy status.

curl -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents/research-agent

# Response
{
  "name": "research-agent",
  "status": "running",
  "port": 2222,
  "owner": "admin",
  "is_owner": true,
  "autonomy_enabled": true,
  "read_only_enabled": false,
  "runtime": "claude-code",
  "avatar_url": "/api/agents/research-agent/avatar?v=1706..."
}

DELETE

/api/agents/:name

Delete an agent and all associated resources (container, volume, schedules, skills, tags). System agents cannot be deleted.

curl -X DELETE -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents/research-agent

# Response
{"message": "Agent research-agent deleted"}

POST

/api/agents/:name/start

Start an agent container. Injects credentials and broadcasts a WebSocket event.

curl -X POST -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents/research-agent/start

# Response
{
  "message": "Agent research-agent started",
  "credentials_injection": "success"
}

POST

/api/agents/:name/stop

Stop an agent container gracefully.

curl -X POST -H "Authorization: Bearer <token>" \
  http://localhost:8000/api/agents/research-agent/stop

# Response
{"message": "Agent research-agent stopped"}

PUT

/api/agents/:name/rename

Rename an agent. Updates all references including container name, volume, and schedules.

Agent Info and Files

Endpoint	Method	Description
/api/agents/{name}/info	GET	Template metadata
/api/agents/{name}/files	GET	Workspace file tree
/api/agents/{name}/files/download	GET	Download file
/api/agents/{name}/logs	GET	Container logs
/api/agents/{name}/stats	GET	Live telemetry
/api/agents/{name}/analytics	GET	Multi-day execution analytics for the Overview tab

GET

/api/agents/:name/logs

Get agent container logs. Useful for debugging startup issues.

Name	Type	Required	Description
tail	integer	No	Number of log lines to return (default: 100)

curl -H "Authorization: Bearer <token>" \
  "http://localhost:8000/api/agents/research-agent/logs?tail=50"

# Response
{"logs": "Starting agent server...\n..."}

GET

/api/agents/:name/stats

Get live container stats including CPU usage, memory, and network I/O.

GET

/api/agents/:name/analytics

Multi-day execution analytics for the Overview tab.

Name	Type	Required	Description
window	string	No	"7d", "14d", or "30d" (default: "7d")

GET

/api/agents/:name/info

Get template metadata for an agent including capabilities and configuration details.

GET

/api/agents/:name/files

Get the workspace file tree for an agent container.

GET

/api/agents/:name/files/download

Download a file from the agent's workspace.

Configuration

Endpoint	Method	Description
/api/agents/{name}/autonomy	GET/PUT	Autonomy mode
/api/agents/{name}/read-only	GET/PUT	Read-only mode
/api/agents/{name}/timeout	GET/PUT	Execution timeout (PUT rejects a cap below any active schedule's timeout with 400)
/api/agents/{name}/ssh-access	POST	Generate SSH credentials
/api/agents/{name}/circuit-breaker	GET/PUT	Circuit breaker state / per-agent enable-disable (owner-only)
/api/agents/{name}/circuit-breaker/reset	POST	Reset both breakers to closed (admin-only)

GET/PUT

/api/agents/:name/autonomy

Get or set the autonomy mode for an agent. When enabled, the agent can execute tasks without manual approval.

GET/PUT

/api/agents/:name/read-only

Get or set read-only mode. When enabled, the agent cannot modify its workspace files.

GET/PUT

/api/agents/:name/timeout

Get or set the execution timeout for an agent. PUT rejects a cap below any active schedule's timeout with 400.

POST

/api/agents/:name/ssh-access

Generate SSH credentials for direct container access.

GET/PUT

/api/agents/:name/circuit-breaker

Get the circuit breaker state, or enable/disable the breaker per agent (owner-only).

POST

/api/agents/:name/circuit-breaker/reset

Reset both breakers to closed (admin-only).

Credentials

Endpoint	Method	Description
/api/agents/{name}/credentials/status	GET	Check credential files
/api/agents/{name}/credentials/inject	POST	Inject credentials
/api/agents/{name}/credentials/export	POST	Export encrypted
/api/agents/{name}/credentials/import	POST	Import encrypted

GET

/api/agents/:name/credentials/status

Check which credential files exist in the agent container.

POST

/api/agents/:name/credentials/inject

Inject credentials into a running agent container. Copies credential files from the host.

POST

/api/agents/:name/credentials/export

Export agent credentials as an encrypted bundle for backup or transfer.

POST

/api/agents/:name/credentials/import

Import credentials from an encrypted bundle into the agent.

Sharing

Endpoint	Method	Description
/api/agents/{name}/share	POST	Share with email
/api/agents/{name}/share/{email}	DELETE	Remove share
/api/agents/{name}/shares	GET	List shares

POST

/api/agents/:name/share

Share an agent with another user by email address.

DELETE

/api/agents/:name/share/:email

Remove a share for a specific email address.

GET

/api/agents/:name/shares

List all users an agent is shared with.

Loops

Sequential bounded task execution against one agent.

Endpoint	Method	Description
/api/agents/{name}/loops	POST	Start a loop (202 with loop_id)
/api/agents/{name}/loops	GET	List the agent's loops
/api/loops/{loop_id}	GET	Loop status, per-run summaries, last response
/api/loops/{loop_id}/stop	POST	Graceful stop (current iteration finishes)

Start-loop request body

message (required), max_runs (1–100, required), and optional stop_signal, delay_seconds, timeout_per_run, max_duration_seconds (wall-clock deadline), max_cost_usd (> 0; total USD budget), model, and allowed_tools.

The cost budget and the deadline are both iteration-boundary stops — checked between runs, so the current run always finishes (one run, including the first, can overshoot).

The loop's stop_reason is one of max_runs_reached, stop_signal_matched, user_stopped, deadline_exceeded, budget_exhausted, error, or interrupted. GET /api/loops/{loop_id} also returns max_cost_usd and total_cost (sum of per-run cost, 0.0 for a zero-run loop).

GET

/api/agents/:name/loops

List the agent's loops.

Name	Type	Required	Description
status	string	No	Filter by loop status
limit	integer	No	Max results

VoIP

Outbound phone calls — flag-gated, off by default.

Endpoint	Method	Description
/api/agents/{name}/voip	GET/PUT/DELETE	Voice binding status / configure / remove (owner)
/api/agents/{name}/voip/call	POST	Place an outbound call (rate-limited, daily-capped; accepts Idempotency-Key)

Shared Folders

Endpoint	Method	Description
/api/agents/{name}/folders	GET/PUT	Folder config
/api/agents/{name}/folders/available	GET	Mountable folders
/api/agents/{name}/folders/consumers	GET	Consuming agents

GET/PUT

/api/agents/:name/folders

Get or update the shared folder configuration for an agent.

GET

/api/agents/:name/folders/available

List folders available for mounting (published by other agents).

GET

/api/agents/:name/folders/consumers

List agents that are consuming this agent's shared folders.

Bulk / Fleet Operations

Endpoint	Method	Description
/api/agents/context-stats	GET	All agents context stats
/api/agents/autonomy-status	GET	All agents autonomy
/api/executions	GET	Paginated fleet execution list
/api/executions/stats	GET	Fleet execution stat cards (windowed by hours; live running/queued counts)

GET

/api/agents/context-stats

Get context window usage statistics for all agents at once.

GET

/api/agents/autonomy-status

Get autonomy mode status for all agents at once.

GET

/api/executions

Paginated fleet execution list.

Name	Type	Required	Description
status	string	No	Filter by execution status
triggered_by	string	No	Filter by trigger source
hours	integer	No	Time window filter
agent	string	No	Filter by agent name
search	string	No	Text search filter

GET

/api/executions/stats

Fleet execution stat cards. Windowed by hours; includes live running/queued counts.

Agent-Internal

Endpoint	Method	Description
/api/agents/{name}/heartbeat	POST	Liveness heartbeat posted by the agent container every 5s

The heartbeat endpoint is authenticated with the agent's own agent-scoped MCP key. Not for external callers.

Idempotency

Execution-triggering endpoints accept an optional Idempotency-Key header for safe retries — see Chat API → Idempotency.

Agent Model

Field	Type	Description
name	string	Unique agent name
type	string	Agent type (default: "business-assistant")
status	string	running, stopped, or exited
port	integer	SSH port for the agent container
created	datetime	ISO 8601 creation timestamp
runtime	string	"claude-code" or "gemini-cli"
resources	object	CPU and memory limits, e.g. {"cpu": "2", "memory": "4g"}
template	string?	Template used for initialization
container_id	string?	Docker container ID

Error Responses

Status	Meaning
401	Invalid or missing JWT token
403	Permission denied (not owner/admin, or system agent)
404	Agent not found
500	Server error (e.g. Docker failure)

Authentication Chat API