From ffd865e72fd66fb495c777490498eb8417db9bd6 Mon Sep 17 00:00:00 2001
From: David Gageot <david.gageot@docker.com>
Date: Sun, 22 Mar 2026 12:15:56 +0100
Subject: [PATCH] docs: clarify :agent and :name parameters in API server
 endpoints

Document that :agent is the config filename without the .yaml extension and
:name is the optional sub-agent name (defaults to root). Add concrete
examples for single-agent and multi-agent configurations.

Fixes #2074

Assisted-By: docker-agent
---
 docs/features/api-server/index.md | 31 ++++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/features/api-server/index.md b/docs/features/api-server/index.md
index ff69f4f00..40f95f709 100644
--- a/docs/features/api-server/index.md
+++ b/docs/features/api-server/index.md
@@ -58,6 +58,34 @@ All endpoints are under the `/api` prefix.
 | `POST` | `/api/sessions/:id/agent/:agent`       | Run the root agent for a session (SSE stream) |
 | `POST` | `/api/sessions/:id/agent/:agent/:name` | Run a specific named agent (SSE stream)       |
 
+**Path parameters:**
+
+- **`:agent`** — The agent identifier, which is the **config filename without the `.yaml` extension**. This must match the filename passed to `docker agent serve api`. For example, if you start the server with `docker agent serve api my-assistant.yaml`, the agent identifier is `my-assistant`. When serving a directory of YAML files, each file becomes a separate agent identified by its filename without the extension.
+- **`:name`** _(optional)_ — The name of a specific sub-agent defined in a multi-agent configuration. If omitted, the request targets the `root` agent. For example, in a config that defines agents named `root`, `coder`, and `reviewer`, use `/api/sessions/:id/agent/my-config/coder` to run the `coder` sub-agent directly.
+
+**Examples:**
+
+```bash
+# Single-agent config: my-assistant.yaml
+# Start: docker agent serve api my-assistant.yaml
+# Run the root agent:
+curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/my-assistant \
+  -H "Content-Type: application/json" \
+  -d '[{"role": "user", "content": "Hello!"}]'
+
+# Multi-agent config: team.yaml (defines agents: root, coder, reviewer)
+# Start: docker agent serve api team.yaml
+# Run the root agent:
+curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/team \
+  -H "Content-Type: application/json" \
+  -d '[{"role": "user", "content": "Review this PR"}]'
+
+# Run a specific sub-agent (reviewer):
+curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/team/reviewer \
+  -H "Content-Type: application/json" \
+  -d '[{"role": "user", "content": "Review this PR"}]'
+```
+
 ### Health
 
 | Method | Path        | Description                               |
@@ -66,10 +94,11 @@ All endpoints are under the `/api` prefix.
 
 ## Streaming Responses
 
-The agent execution endpoints (`POST /api/sessions/:id/agent/:agent`) return **Server-Sent Events (SSE)**. Each event is a JSON object representing a runtime event:
+The agent execution endpoints (`POST /api/sessions/:id/agent/:agent`) return **Server-Sent Events (SSE)**. Each event is a JSON object representing a runtime event (remember that `:agent` is the config filename without the `.yaml` extension):
 
 ```bash
 # Send a message and stream the response
+# (assuming the server was started with: docker agent serve api my-agent.yaml)
 $ curl -N -X POST http://localhost:8080/api/sessions/$SID/agent/my-agent \
   -H "Content-Type: application/json" \
   -d '[{"role": "user", "content": "Hello!"}]'