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

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/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
/api/agents/{name}/ssh-access	POST	Generate SSH credentials

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.

POST

/api/agents/:name/ssh-access

Generate SSH credentials for direct container access.

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.

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

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.

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