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.
/api/agents/:name/voice/ws
WebSocket endpoint for bidirectional audio streaming. Used as the audio bridge for voice chat.
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.
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 |
| /api/agents/{name}/voice/ws | WS | Audio WebSocket bridge |
| /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 |