API reference.
Aria is reachable over HTTP. Live chat is a server-streamed, OAuth-authenticated endpoint; the public demo is a separate route with hardcoded context.
Base host
app.corvanahq.com
Schema version
v1.0.0
Transport
HTTPS + text/plain stream
Honest defaults
/v1 prefix, API keys, OAuth public clients, or webhooks today. The only callable surfaces are the two chat routes below. Retrieval endpoints are designed but labeled Planned until they ship.Base URL and transport
All requests go to the app origin over HTTPS. The chat routes stream their bodies as text/plain; charset=utf-8, not text/event-stream — a streamed SSE upgrade is on the near-term roadmap and will be additive. Every request must use HTTPS; HTTP is not served.
curl -N -X POST https://app.corvanahq.com/api/chat \
-H "Content-Type: application/json" \
-H "Cookie: __Secure-authjs.session-token=…" \
-d '{"messages":[{"role":"user","content":"Where are we leaking time?"}]}'Endpoints
Authentication
StableOAuth sign-in (Google, Microsoft Entra, GitHub) and database-backed session cookies. There is no API key system today.
Live chat
StablePOST/api/chatAuthenticated streaming chat endpoint. Persists turns to Postgres, bumps engagement state, and returns the conversation ID.
Demo chat
StablePOST/api/chat/demoUnauthenticated, IP-rate-limited public endpoint backed by a hardcoded engagement context. No persistence.
Errors
StableThe full set of error codes Aria returns today, plus the envelope planned for the JSON endpoints rolling out next.
Rate limits
StablePer-user and per-IP limits, the backing store, and the headers you should read to back off gracefully.
Conversation retrieval
PlannedGET/api/conversationsList conversations, fetch messages, and archive. The tables exist; the endpoints roll out with the retrieval preview.
Response envelope
The chat endpoints stream raw text — there is no JSON envelope around the assistant reply. The retrieval endpoints rolling out next will use a consistent shape:
{
"data": { /* resource or list */ },
"meta": {
"requestId": "req_01HW…",
"nextCursor": "cmvw…"
}
}Errors on those endpoints return the structured envelope documented under Errors.
Request IDs and observability
Every response carries X-Request-Id — an echo of the client value if sent, otherwise a server-generated ULID. The live chat endpoint also returns X-Prompt-Version (the composed system-prompt version) and X-Conversation-Id when a turn is tied to a persisted conversation. Server logs include the upstream Anthropic requestID under upstreamRequestId for correlation, but it is deliberately not exposed on the response.
Planned surfaces
The Postgres schema already supports conversation retrieval, archived status, engagement-state fetching, and programmatic onboarding. The endpoints below are specified but not yet deployed. When they land, they ship with the envelope above and the headers in the Observability note.
GET /api/conversations— list active conversations for the caller's org.GET /api/conversations/:id/messages— fetch the full message history for a conversation.POST /api/conversations/:id/archive— archive a conversation without deleting it.GET /api/engagement— fetch the current engagement state (week, hypotheses, unknowns, findings).POST /api/onboarding— single-payload onboarding for programmatic sign-up.
Not supported today
Server-to-server authentication (API keys, client credentials) is not supported today. Every call must carry a NextAuth session cookie belonging to a signed-in, onboarded user. Track progress on programmatic access in the newsroom.