Skip to main content
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

The API token (api_token) lives in the vault — pnpm run setup generates and seeds it, or set your own with API_TOKEN=... pnpm run seed-vault. Every request (except GET /api/health) must include the token in the Authorization header: 
Authorization: Bearer <your-token>
If no API token is configured, 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
GET /api/autonomyCurrent autonomy score, band, trend direction, lastSetBy, and scored action count
PUT /api/autonomySet the autonomy score (body: { "score": 85, "reason": "..." })
GET /api/autonomy/historyPaginated autonomy score change history (query: limit, offset)
GET /api/registry/skillsList registered skills with installed/enabled state
GET /api/registry/agentsList registered agents with installed/enabled state
POST /api/registry/:kind/:name/installInstall a skill or agent (kind is skills or agents)
POST /api/registry/:kind/:name/enableEnable an installed skill or agent
POST /api/registry/:kind/:name/install-enableInstall and enable in one call
POST /api/registry/:kind/:name/disableDisable a skill or agent
DELETE /api/registry/:kind/:nameUninstall a skill or agent
GET /api/vault/*Manage vault secrets and channel credentials (names only; values are never returned)
See Managing skills, agents, and channels for how the registry and required-secret gates work.

​
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