Skip to main content
The docker agent serve api command starts an HTTP server that exposes your agents through a REST-style API with Server-Sent Events (SSE) streaming.

​
Starting the server

# Start with a local config
docker agent serve api agent.yaml

# Custom listen address
docker agent serve api agent.yaml --listen 0.0.0.0:8080

# With explicit session database
docker agent serve api agent.yaml --session-db ./sessions.db

# Auto-refresh from OCI registry every 10 minutes
docker agent serve api agentcatalog/coder --pull-interval 10

​
Flags

FlagDefaultDescription
-l, --listen <addr>127.0.0.1:8080Address to listen on
-s, --session-db <path>session.dbPath to the SQLite session database
--pull-interval <mins>0 (disabled)Auto-pull OCI reference every N minutes
--working-dir <path>(current dir)Working directory for sessions

​
Endpoints

All endpoints are under the /api prefix.

​
Agents

MethodPathDescription
GET/api/agentsList all available agents
GET/api/agents/:idGet a specific agent’s configuration

​
Sessions

MethodPathDescription
GET/api/sessionsList all sessions
POST/api/sessionsCreate a new session
GET/api/sessions/:idGet a session by ID (messages, tokens, permissions)
DELETE/api/sessions/:idDelete a session
PATCH/api/sessions/:id/titleUpdate the session title
PATCH/api/sessions/:id/permissionsUpdate session permissions
POST/api/sessions/:id/resumeResume a paused session (after tool confirmation)
POST/api/sessions/:id/tools/toggleToggle auto-approve (YOLO) mode
POST/api/sessions/:id/elicitationRespond to an MCP tool elicitation request

​
Agent execution

MethodPathDescription
POST/api/sessions/:id/agent/:agentRun the root agent (SSE stream)
POST/api/sessions/:id/agent/:agent/:nameRun a specific named agent (SSE stream)

​
Health

MethodPathDescription
GET/api/pingHealth check — returns {"status": "ok"}

​
Streaming responses

Agent execution endpoints return Server-Sent Events (SSE). Each event is a JSON object: 
# Create a session
SID=$(curl -s -X POST http://localhost:8080/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"agent": "root"}' | jq -r '.id')

# Run the agent (SSE stream)
curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/root \
  -H "Content-Type: application/json" \
  -d '[{"role": "user", "content": "Hello!"}]'
Example SSE response: 
data: {"type":"stream_started","session_id":"...","agent":"root"}
data: {"type":"agent_choice","content":"Hello! How","agent":"root"}
data: {"type":"agent_choice","content":" can I help","agent":"root"}
data: {"type":"agent_choice","content":" you today?","agent":"root"}
data: {"type":"stream_end","session_id":"..."}

​
Integration patterns

Build a chat UI that creates sessions via POST /api/sessions, then streams responses using the EventSource API:
const response = await fetch(`/api/sessions/${sessionId}/agent/root`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify([{ role: 'user', content: userMessage }]),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  // Parse SSE events and update UI
}

Build docs developers (and LLMs) love

Get started for freeTalk to us