Skip to main content

Documentation Index

Fetch the complete documentation index at: https://curia.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

POST /api/messages is the primary way to interact with Curia programmatically. You send a message, Curia routes it to the Coordinator agent, and the response comes back in the same HTTP reply — no streaming required. If you want to watch the agent’s progress in real time (for example, to see which tools it is calling), use GET /api/messages/stream alongside this endpoint.

​
Request

POST /api/messages
The request body must be JSON. Set Content-Type: application/json on every call.

​
Request body

​
content
string
required
The message text to send to the Coordinator. Must be a non-empty string. The body limit for the entire request is 64 KiB; messages approaching that size will be rejected with 413.
​
conversation_id
string
An identifier for the conversation thread. Pass the same value across multiple requests to continue an existing conversation — the agent uses this to retrieve prior context from memory. If you omit this field, Curia generates a new ID (prefixed http-) and returns it in the response. Save it if you want to continue the thread later.
​
sender_id
string
default:"http-user"
An identifier for the sender. Defaults to http-user if not provided. Use this to distinguish between different callers in your logs or when building multi-user integrations.

​
Example request

curl -X POST http://localhost:3000/api/messages \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"content": "What meetings do I have tomorrow?"}'
To continue an existing conversation, include the conversation_id from a previous response: 
curl -X POST http://localhost:3000/api/messages \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Can you move the 10am one to 2pm?",
    "conversation_id": "http-abc123..."
  }'

​
Response

A successful response has HTTP status 200 and a JSON body.

​
Response fields

​
conversation_id
string
required
The conversation thread ID. If you provided one in the request, this echoes it back. If you did not, this is the newly generated ID — save it to continue the thread in future requests.
​
content
string
required
The agent’s reply as plain text.
​
agent_id
string
required
The identifier of the agent that handled the request. Currently always "coordinator".

​
Example response

{
  "conversation_id": "http-abc123...",
  "content": "You have two meetings tomorrow: a 10am product sync and a 3pm investor call.",
  "agent_id": "coordinator"
}

​
Conversation threading

Each conversation_id represents a persistent thread. The agent retrieves relevant memory from that thread when formulating its reply, so passing the same ID lets you have a multi-turn conversation without repeating context.
1

Start a new conversation

Omit conversation_id. Curia generates one and returns it in the response.
curl -X POST http://localhost:3000/api/messages \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"content": "Summarize my emails from this morning."}'
2

Save the conversation ID

Extract conversation_id from the response and store it in your client.
{ "conversation_id": "http-f47ac10b-58cc-4372-a567-0e02b2c3d479", "content": "...", "agent_id": "coordinator" }
3

Continue the thread

Pass the saved conversation_id on your next request.
curl -X POST http://localhost:3000/api/messages \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Which of those needs a reply today?",
    "conversation_id": "http-f47ac10b-58cc-4372-a567-0e02b2c3d479"
  }'

​
Error responses

The content field was absent or contained only whitespace.
{ "error": "Missing required field: content (non-empty string)" }
The Authorization header was missing or the Bearer token did not match.
{ "error": "Unauthorized — provide a valid Bearer token" }
The request body exceeded the 64 KiB limit. Shorten your message.
{ "error": "request body is too large" }
You have exceeded the 200 requests per minute global limit.
{ "error": "Rate limit exceeded, retry in 1 minute" }
The agent did not produce a response within 120 seconds. This can happen if the agent is waiting for a slow external tool. Retry your request or break the task into smaller steps.
{ "error": "Response timeout" }
An unexpected error occurred while publishing your message to the internal bus. Check your Curia server logs for details.
{ "error": "A description of what went wrong." }