Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
API Reference

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

EndpointMethodDescription
/api/agentsGETList the agents the caller may see — an admin every agent, anyone else their owned and shared agents, an agent-scoped key only its reach (itself, the agents it may call, the agents it spawned; see Agent Permissions). Each row carries readiness ({status, changed_at, source} for an agent whose owner stamped it ready or calibrating, otherwise null) and brief_held — see Dashboard
/api/agentsPOSTCreate agent. On a github: template, optional kind (agent default, or deployment); the response's git_mode says whether the agent pushes and why — see GitHub Sync
/api/agents/{name}GETGet agent details
/api/agents/{name}DELETEDelete agent
/api/agents/{name}/startPOSTStart container
/api/agents/{name}/stopPOSTStop container
/api/agents/{name}/renamePUTRename agent (moves the slug)
/api/agents/{name}/labelGET/PUTDisplay label ({"label": "My Agent"}; null or empty clears it back to the slug) — see Managing Agents
GET

/api/agents

List the agents the caller may see (admins: every agent; others: owned and shared agents; agent-scoped keys: only their reach). Supports filtering by tags.

NameTypeRequiredDescription
tagsstringNoComma-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.

NameTypeRequiredDescription
namestringYesUnique agent name
typestringNoAgent type (default: "business-assistant")
templatestringNoTemplate to initialize from
runtimestringNo"claude-code", "gemini-cli" or "codex"
runtime_modelstringNoModel override (e.g. "sonnet-4.5")
resourcesobjectNo{"cpu": "2", "memory": "4g"}
custom_instructionsstringNoCustom system prompt
github_repostringNoGitHub 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

EndpointMethodDescription
/api/agents/{name}/infoGETTemplate metadata
/api/agents/{name}/filesGET/PUT/DELETEWorkspace file tree / save a text file / delete a file. Each verb is ruled per path and caller tier (owner, share, key); the tree flags each node with the verbs the caller may not use, and a refusal is 403 with a named code — see Agent Files
/api/agents/{name}/files/downloadGETDownload file
/api/agents/{name}/logsGETContainer logs
/api/agents/{name}/statsGETLive telemetry
/api/agents/{name}/analyticsGETMulti-day execution analytics for the Overview tab
GET

/api/agents/:name/logs

Get agent container logs. Useful for debugging startup issues.

NameTypeRequiredDescription
tailintegerNoNumber 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.

NameTypeRequiredDescription
windowstringNo"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.

Metrics and Objectives

EndpointMethodDescription
/api/agents/{name}/metricsGETDeclared metrics joined to recorded points, with a freshness verdict per metric. Works for a stopped agent. An agent key reads only its own
/api/agents/{name}/metrics/pointsPOSTRecord a batch of metric points (all-or-nothing; accepts Idempotency-Key). An agent key records only as itself
/api/agents/{name}/metrics/definitionsGETThe declared-metric registry built from template.yaml metrics:
/api/agents/{name}/metrics/definitions/refreshPOSTRe-read template.yaml into the registry (agent must be running)
/api/agents/{name}/metrics/declarationsGETWhat template.yaml metrics: declares, as written, with the template_hash every write sends back (owner tier)
/api/agents/{name}/metrics/declarationsPOSTDeclare a metric: add one metrics: entry to template.yaml (owner tier, agent running)
/api/agents/{name}/metrics/declarations/{metric}PUTEdit one declared metric; name and type cannot change (owner tier, agent running)
/api/agents/{name}/metrics/declarations/{metric}/referencesGETWhat still uses a metric: recorded points, objectives, dashboard widgets, linked projects
/api/agents/{name}/metrics/declarations/{metric}DELETERetire a metric: remove its entry (?base_hash=; ?acknowledge_references=true when it is in use)
/api/agents/{name}/objectivesGETObjectives joined to metrics — target, actual, freshness, gap. An agent key reads only its own

See Dynamic Dashboards for declared metrics.

Configuration

EndpointMethodDescription
/api/agents/{name}/autonomyGET/PUTAutonomy mode
/api/agents/{name}/read-onlyGET/PUTRead-only mode
/api/agents/{name}/timeoutGET/PUTExecution timeout (PUT rejects a cap below any active schedule's timeout with 400)
/api/agents/{name}/ssh-accessPOSTGenerate SSH credentials
/api/agents/{name}/circuit-breakerGET/PUTCircuit breaker state / per-agent enable-disable (owner-only) — see Agent Configuration
/api/agents/{name}/circuit-breaker/resetPOSTReset both breakers to closed (admin-only)
/api/agents/{name}/operator-resumeGET/PUTWake the agent when an ask it raised ends — answered or cancelled — or when a run it delegated ends ({"enabled": true}, or {"mode": "default" | "on" | "off"}; on by default). GET for anyone with access; PUT is owner or admin, and an agent-scoped key gets 403 — see Agent Configuration
/api/agents/{name}/operator-queue/{request_id}GETThe agent's own operator-queue item by the id it chose, with the agent's own key only — how it stands and how it ended
/api/agents/{name}/resourcesGET/PUTMemory and CPU limits (applied on the next recreate). A CPU limit above the Docker host's CPU count runs capped at the host's count; the stored value is kept
/api/agents/{name}/capabilitiesGET/PUTfull_capabilities — Docker default capabilities (apt-get works) vs the restricted secure default — see Agent Configuration
/api/agents/{name}/mcp-exposedGET/PUTPublish the agent as its own chat_with_<slug> MCP tool — see MCP Integration
/api/agents/{name}/mcp-keyGETThe 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).

Git

Git status, sync, pull, auto-sync, pull-sync, schedule-pause and per-agent GitHub token endpoints live under /api/agents/{name}/git/… and /api/agents/{name}/github-pat — see GitHub Sync and GitHub PAT Setup.

Credentials

EndpointMethodDescription
/api/agents/{name}/credentials/statusGETCheck credential files
/api/agents/{name}/credentials/injectPOSTInject credentials
/api/agents/{name}/credentials/exportPOSTExport encrypted
/api/agents/{name}/credentials/importPOSTImport encrypted
/api/agents/{name}/credential-requirementsGETPer-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

EndpointMethodDescription
/api/agents/{name}/sharePOSTShare with email
/api/agents/{name}/share/{email}DELETERemove share
/api/agents/{name}/sharesGETList 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.

EndpointMethodDescription
/api/agents/{name}/schedulesGET/POSTList/create
/api/agents/{name}/schedules/{id}GET/PUT/DELETECRUD
/api/agents/{name}/schedules/{id}/enablePOSTEnable
/api/agents/{name}/schedules/{id}/disablePOSTDisable
/api/agents/{name}/schedules/{id}/triggerPOSTManual trigger
/api/agents/{name}/schedules/{id}/executionsGETHistory
/api/agents/{name}/schedules/{id}/analyticsGETPer-schedule analytics (?window_hours=24|168|720) — see Scheduling

Loops

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

EndpointMethodDescription
/api/agents/{name}/loopsPOSTStart a loop (202 with loop_id)
/api/agents/{name}/loopsGETList the agent's loops
/api/loops/{loop_id}GETLoop status, per-run summaries, last response
/api/loops/{loop_id}/stopPOSTGraceful 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.

NameTypeRequiredDescription
statusstringNoFilter by loop status
limitintegerNoMax results

VoIP

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

EndpointMethodDescription
/api/agents/{name}/voipGET/PUT/DELETEVoice binding status / configure / remove (owner)
/api/agents/{name}/voip/enabledPUTEnable or disable calling without re-entering credentials (owner)
/api/agents/{name}/voip/callPOSTPlace an outbound call (rate-limited, daily-capped; accepts Idempotency-Key)

Shared Folders

EndpointMethodDescription
/api/agents/{name}/foldersGET/PUTFolder config
/api/agents/{name}/folders/availableGETMountable folders
/api/agents/{name}/folders/consumersGETConsuming 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

EndpointMethodDescription
/api/agents/context-statsGETAll agents context stats
/api/agents/autonomy-statusGETAll agents autonomy
/api/executionsGETPaginated fleet execution list (filters: status, triggered_by, hours, agent, search) — see Executions
/api/executions/statsGETFleet 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.

NameTypeRequiredDescription
statusstringNoFilter by execution status
triggered_bystringNoFilter by trigger source
hoursintegerNoTime window filter
agentstringNoFilter by agent name
searchstringNoText search filter
GET

/api/executions/stats

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

Agent-Internal

EndpointMethodDescription
/api/agents/{name}/heartbeatPOSTLiveness 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

FieldTypeDescription
namestringUnique agent name
typestringAgent type (default: "business-assistant")
statusstringrunning, stopped, or exited
portintegerSSH port for the agent container
createddatetimeISO 8601 creation timestamp
runtimestring"claude-code", "gemini-cli" or "codex"
resourcesobjectCPU and memory limits, e.g. {"cpu": "2", "memory": "4g"}
templatestring?Template used for initialization
container_idstring?Docker container ID

Error Responses

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