Chat API
API endpoints for agent chat, voice, streaming, and public chat access. All endpoints require JWT Bearer token unless noted. See Authentication for details.
Full interactive API docs are available at http://localhost:8000/docs when running locally.
Authenticated Chat
/api/agents/:name/chat
Send a message to an agent. Returns stream-json output for real-time responses.
curl -X POST -H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"message": "Summarize the latest research findings"}' \
http://localhost:8000/api/agents/research-agent/chat/api/agents/:name/chat/sessions
List all chat sessions for an agent.
/api/agents/:name/chat/sessions/:id
Get a specific session with all its messages.
/api/agents/:name/chat/sessions/:id/close
Close a chat session.
/api/agents/:name/chat/history/persistent
Get persistent chat history across sessions.
/api/agents/:name/chat/history
Reset the current chat session.
/api/agents/:name/activity
Get an activity summary for the agent.
Voice Chat
/api/agents/:name/voice/start
Start a voice chat session with an agent.
/api/agents/:name/voice/stop
Stop a voice chat session.
/api/agents/:name/voice/status
Get the current voice session status.
/ws/voice/:session_id
WebSocket endpoint for bidirectional audio streaming. Used as the audio bridge for voice chat — the URL is returned by voice/start.
Public Chat (No Auth)
Public chat endpoints do not require authentication. They use a unique token to identify the public chat session.
/api/public/chat/:token
Send a message via public chat using a share token.
/api/public/history/:token
Get chat history for a public chat session.
Paid Chat (x402)
Paid chat endpoints use the x402 payment protocol. Clients receive a 402 response with payment requirements, then resubmit with a payment proof header.
/api/paid/:agent_name/chat
Send a paid chat message. Returns 402 with payment requirements or 200 with the response.
/api/paid/:agent_name/info
Get payment requirements and pricing info for an agent.
Task Execution
/api/agents/:name/task
Submit a task for asynchronous execution. Tasks are queued and executed by the agent.
curl -X POST -H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"message": "Generate a report on Q1 sales data"}' \
http://localhost:8000/api/agents/research-agent/task/api/agents/:name/executions
List all executions (tasks and schedule runs) for an agent.
/api/agents/:name/executions/:id
Get full details of a specific execution including response, errors, and tool calls.
Deprecated: per-task timeout_seconds
The timeout_seconds field on the task request body is deprecatedand will be removed in a future release. The agent's execution timeout (GET/PUT /api/agents/{name}/timeout) is authoritative.
Current behavior: the field is still honored, but values above the agent's timeout cap are clamped down to the cap (the server logs a deprecation warning). Omit the field — the task then uses the agent's configured timeout. To run longer tasks, raise the agent's timeout cap instead.
Idempotency
Endpoints that trigger an execution accept an optional Idempotency-Key header so you can retry safely without creating duplicate executions. Pick any unique string per logical request (e.g., a UUID) and resend it on retry:
curl -X POST http://localhost:8000/api/agents/my-agent/task \
-H "Authorization: Bearer <token>" \
-H "Idempotency-Key: 7f3a2c1e-..." \
-H "Content-Type: application/json" \
-d '{"message": "Summarize the latest reports"}'- The same key within 24 hours returns the original result with the header
X-Idempotent-Replay: true— no second execution is created. - A duplicate sent while the first request is still running returns 409 with the original
execution_idto poll. - If the first attempt was rejected before dispatch (e.g., at capacity), the key is released so the retry goes through.
- The header is optional and fail-open: omitting it preserves normal behavior, and a dedup-layer error never blocks a real request.
Wired boundaries: /api/agents/{name}/chat, /api/agents/{name}/task, /api/agents/{name}/fan-out, /api/agents/{name}/voip/call, webhook triggers (key auto-derived from token + body when the header is absent), and the MCP chat_with_agent / fan_out tools (deterministic key derived from the call arguments).
Endpoint Summary
| Endpoint | Method | Description |
|---|---|---|
| /api/agents/{name}/chat | POST | Send message (stream-json output) |
| /api/agents/{name}/chat/sessions | GET | List sessions |
| /api/agents/{name}/chat/sessions/{id} | GET | Session with messages |
| /api/agents/{name}/chat/sessions/{id}/close | POST | Close session |
| /api/agents/{name}/chat/history/persistent | GET | Persistent history |
| /api/agents/{name}/chat/history | DELETE | Reset session |
| /api/agents/{name}/activity | GET | Activity summary |
| /api/agents/{name}/voice/start | POST | Start voice session |
| /api/agents/{name}/voice/stop | POST | Stop session |
| /api/agents/{name}/voice/status | GET | Session status |
| /ws/voice/{session_id} | WS | Audio WebSocket bridge (URL returned by voice/start) |
| /api/public/chat/{token} | POST | Public chat |
| /api/public/history/{token} | GET | Public history |
| /api/paid/{agent_name}/chat | POST | Paid chat (402/200) |
| /api/paid/{agent_name}/info | GET | Payment requirements |
| /api/agents/{name}/task | POST | Submit task |
| /api/agents/{name}/executions | GET | List executions |
| /api/agents/{name}/executions/{id} | GET | Execution details |