Qorven’s API lives at /v1/* (with /api as an alias for browser clients coming through the UI’s rewrite chain). Every endpoint requires a bearer token unless noted. All request + response bodies are JSON.

​
Auth

curl https://your-qorven/v1/agents \
  -H "Authorization: Bearer $QORVEN_TOKEN"
Tokens are created at install time. Rotate via Settings → Admin → Tokens or qorven auth rotate-token.

​
Endpoint families

/v1/chat/completions

OpenAI-compatible chat. POST with {session_id, agent_id, message, stream} → streamed SSE with tokens + tool events.

/v1/agents

CRUD for Qors. GET list, POST create, GET/{id} read, PATCH/{id} update, DELETE/{id} soft-delete.

/v1/sessions

Session management. Idempotent POST returns the canonical session for chat-family channels.

/v1/messages

Per-session message list. Filterable by channel.

/v1/memory/search

POST {scope, agent_id, query, max_results} → ranked memory list with relevance scores.

/v1/memory/save

Write a memory directly (bypasses the agent loop — for admin use).

/v1/tools

List + inspect tools. POST /v1/tools/{id}/invoke bypasses the agent loop (admin only).

/v1/rooms

Multi-agent rooms. Create, post messages, decide.

/v1/channels

Channel binding CRUD + /status + /test-routing.

/v1/models

Model catalog, selected models, default model.

/v1/providers

LLM provider CRUD; /keys for keys.

/v1/webhooks/{channel}

Per-channel inbound webhooks. Signature-verified by the channel’s own spec.

/ws

WebSocket hub. Subscribe to session events + Qor activity.

/health, /livez, /readyz

Health probes. /livez = process up, /readyz = deps warmed.

​
OpenAPI spec

The machine-readable spec is at /openapi.json on every install. Import into Postman, Bruno, or use with typed clients.

​
Rate limits

ScopeDefaultResponse on breach
Per-IP10 req/sec, burst 20429 + Retry-After
Per-tenant600 req/min429 + Retry-After
Per-tenant concurrent5 plan-runs503 + Retry-After
Tuning rate limits →

​
Pagination

List endpoints support cursor-based pagination: 
GET /v1/agents?limit=50&after=<cursor>
Response headers: 
X-Next-Cursor: eyJpZCI6InVyaW4uLi4ifQ==
X-Total: 120

​
Errors

Machine-readable: 
{
  "error": {
    "code": "provider_rate_limited",
    "message": "OpenAI rate-limited this key; all keys exhausted",
    "details": { "provider": "openai", "retry_after": 14 }
  }
}
Error codes →

​
SDKs (unofficial)

The API is OpenAI-compatible at the chat level. Any OpenAI SDK works for chat: 
from openai import OpenAI
client = OpenAI(base_url="https://your-qorven/v1", api_key=os.environ["QORVEN_TOKEN"])
resp = client.chat.completions.create(
    model="prime",
    messages=[{"role":"user","content":"Plan my week"}],
)
For Qorven-specific endpoints (memory, rooms, delegation), use the HTTP API directly or the Go client in backend/cmd/client/.

​
Where next

Environment variables

QORVEN_SERVER, QORVEN_TOKEN for client apps.

Auth middleware

How tokens are validated.

Rate limits

Tuning for scale.

Error codes

Every error.code string.