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 (moves the slug)
/api/agents/{name}/label	GET/PUT	Display label (`{"label": "My Agent"}`; `null` or empty clears it back to the slug) — see Managing Agents

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/PUT/DELETE	Workspace file tree / save a text file / delete a file — see Agent Files
/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) — see Agent Configuration
/api/agents/{name}/circuit-breaker/reset	POST	Reset both breakers to closed (admin-only)
/api/agents/{name}/operator-resume	GET/PUT	Wake the agent when an operator answers (`{"enabled": true}`). GET for anyone with access; PUT is owner or admin, and an agent-scoped key gets `403` — see Agent Configuration
/api/agents/{name}/resources	GET/PUT	Memory and CPU limits (applied on the next recreate)
/api/agents/{name}/capabilities	GET/PUT	`full_capabilities` — Docker default capabilities (`apt-get` works) vs the restricted secure default — see Agent Configuration
/api/agents/{name}/mcp-exposed	GET/PUT	Publish the agent as its own `chat_with_<slug>` MCP tool — see MCP Integration
/api/agents/{name}/mcp-key	GET	The agent's own MCP key health (never the secret); `POST …/mcp-key/verify` probes the container, `POST …/mcp-key/regenerate` rotates it — see MCP Integration

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
/api/agents/{name}/credential-requirements	GET	Per-variable setup checklist — see Credential Management

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.

Schedules

Full parameters, webhook triggers, and the scheduler's behaviour are on the Schedules & Triggers API page.

Endpoint	Method	Description
/api/agents/{name}/schedules	GET/POST	List/create
/api/agents/{name}/schedules/{id}	GET/PUT/DELETE	CRUD
/api/agents/{name}/schedules/{id}/enable	POST	Enable
/api/agents/{name}/schedules/{id}/disable	POST	Disable
/api/agents/{name}/schedules/{id}/trigger	POST	Manual trigger
/api/agents/{name}/schedules/{id}/executions	GET	History
/api/agents/{name}/schedules/{id}/analytics	GET	Per-schedule analytics (`?window_hours=24\|168\|720`) — see Scheduling

Loops

Sequential bounded task execution against one agent — see Agent Loops for concepts.

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), no_progress_threshold (default 3; 0 disables), on_failure (abort default, or continue), max_consecutive_failures (default 3), model, and allowed_tools.

Budget, deadline, and no-progress stops are all iteration-boundary stops — checked between runs, so the current run always finishes.

The loop's stop_reason is one of max_runs_reached, stop_signal_matched, user_stopped, deadline_exceeded, budget_exhausted, no_progress, or error (interrupted appears only on rows from older builds — loops now survive a backend restart). GET /api/loops/{loop_id} also returns max_cost_usd and total_cost. Parameter semantics are documented in Agent Loops.

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/enabled	PUT	Enable or disable calling without re-entering credentials (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 (filters: `status`, `triggered_by`, `hours`, `agent`, `search`) — see Executions
/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.

Lifecycle notes

Agent containers are created with Docker restart policy unless-stopped: after a host reboot or a Docker daemon restart, every agent that was running comes back on its own, and an agent you stopped (POST …/stop, the Operating Room emergency stop) stays stopped. The policy is applied at container creation, so agents created before this behaviour shipped adopt it on their next recreate (a resource, runtime, or base-image change), not on a plain restart.

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