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.

The Curia HTTP API gives you programmatic access to your assistant from web dashboards, mobile apps, and any integration that speaks HTTP. It exposes a small set of REST endpoints and a Server-Sent Events stream so you can send messages and watch agent activity in real time — all secured with a Bearer token you configure yourself.

​
Base URL

The API listens on port 3000 by default. You can change this by setting HTTP_PORT in your .env file. 
http://localhost:3000
For production deployments behind a reverse proxy, replace localhost:3000 with your domain or internal service address.

​
Authentication

Set API_TOKEN in your .env file to enable authentication. Every request (except GET /api/health) must include the token in the Authorization header: 
Authorization: Bearer <your-token>
If API_TOKEN is not set, authentication is disabled — useful for local development, but not recommended for any network-accessible deployment.
The HTTP channel carries medium trust. It is suited for information queries, scheduling requests, and read-only operations. Actions that require higher trust — such as financial transactions or irreversible operations — must originate from the Signal or CLI channel. If you send a medium-trust request that triggers a high-trust action, Curia will ask you to confirm via a trusted channel before proceeding.

​
Example authenticated request

curl http://localhost:3000/api/messages \
  -X POST \
  -H "Authorization: Bearer your-token-here" \
  -H "Content-Type: application/json" \
  -d '{"content": "What is on my calendar today?"}'
If the token is missing or incorrect, the API returns: 
{ "error": "Unauthorized — provide a valid Bearer token" }

​
Available endpoints

POST /api/messages

Send a message to the Coordinator agent and receive a synchronous response. Supports conversation threading via conversation_id.

GET /api/messages/stream

Open a Server-Sent Events connection to receive agent responses, tool invocations, and tool results in real time.

GET /api/health

Returns the health status of the Curia instance. No authentication required. Use this for uptime monitors and load balancer probes.

GET /api/agents/status

Returns a snapshot of all registered agents and their current state. Requires Bearer token authentication.

​
Dashboard-only endpoints

The following endpoints are used by the built-in web dashboard. They authenticate via session cookie (set by the /auth exchange) rather than a Bearer token, and require WEB_APP_BOOTSTRAP_SECRET to be configured.
EndpointDescription
GET /api/jobsList scheduled jobs, with optional status and agent_id filters
GET /api/jobs/:idGet a single scheduled job by ID
POST /api/jobsCreate a new scheduled job
PATCH /api/jobs/:idUpdate or unsuspend a scheduled job
DELETE /api/jobs/:idCancel (soft-delete) a scheduled job
GET /api/kg/*Knowledge graph browser — nodes, edges, search, and chat

​
Rate limiting

The API enforces a global limit of 200 requests per minute. Stricter per-route limits apply to authentication endpoints to prevent brute-force attacks. When you exceed the limit, the API returns 429 Too Many Requests.

​
Error responses

All errors follow the same JSON format: 
{ "error": "A human-readable description of the problem." }
StatusMeaning
200Success
400Bad request — a required field is missing or invalid
401Unauthorized — token missing or incorrect
413Payload too large — message body exceeds the 64 KiB limit
429Rate limited — slow down and retry
500Internal server error — check your Curia logs
503Service degraded — typically a database connectivity issue
504Gateway timeout — the agent did not respond within 120 seconds