Chat

POST /api/chat

Send a message and receive the complete response (non-streaming). For streaming, use the WebSocket endpoint.

Request

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{
    "text": "What files are in this directory?",
    "user_id": "user123",
    "channel_id": "main",
    "channel_session_key": "550e8400-e29b-41d4-a716-446655440000"
  }'

Request Body

Field	Type	Required	Description
text	string	Yes	The user's message
user_id	string	No	User identifier
channel_id	string	No	Channel name (default: "main")
channel_session_key	string	No	Session identifier

Response

{
  "text": "The directory contains:\n- Cargo.toml\n- README.md\n- src/\n- crates/",
  "session_id": "abc123-def456",
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 85,
    "cache_read_tokens": 0,
    "cache_write_tokens": 0,
    "cost_usd": 0.0032
  }
}

Response Fields

Field	Type	Description
text	string	The agent's response text
session_id	string	The session this message belongs to
usage	object	Token usage and cost
usage.input_tokens	integer	Tokens sent to Claude
usage.output_tokens	integer	Tokens generated by Claude
usage.cache_read_tokens	integer	Tokens read from cache
usage.cache_write_tokens	integer	Tokens written to cache
usage.cost_usd	float	Estimated cost in USD

Session Behavior

• If channel_session_key is provided, the message continues that session
• If omitted, a new session is created
• Sessions on the main channel are explicit — the same key always maps to the same session