API reference

Download the OpenAPI description

Every endpoint, parameter, and error envelope is described in an OpenAPI 3.1 document served by this gateway at /openapi.json. Because it ships inside the binary, it always matches the running build. Import it into Postman, Insomnia, or a code generator:

curl -O ${JANUS_PUBLIC_URL}/openapi.json

The three surfaces

Proxy — PUBLIC_URL/v1/* speaks the OpenAI API and authenticates with a bearer token from the API Tokens page. This is the base URL to configure in SDKs. See “Proxy endpoints” for details.

Application — /api/v1/* serves the web UI: profile, tokens, request log, dashboards, and the team-lead quota endpoints. It authenticates with the browser session cookie or a personal API token (service tokens are refused). Mutating calls made with the session cookie must echo the janus_csrf cookie value in the X-Janus-CSRF header; calls made with a token need no CSRF header.

Admin — /api/v1/admin/* requires the admin role on top of a session. Every mutation is audit-logged with actor and before/after values.

Outside these three: POST /v1/decisions, /v1/systemone and /api/alpha/decisions call decision models with the same bearer token as the proxy. /scim/v2/* takes a SCIM provisioning token from Administration → Settings → Sign-in & provisioning. /auth/* handles sign-in. /healthz (liveness), /readyz (readiness: database and identity provider) and /metrics (Prometheus) need no credentials.

Error envelope

Every error Janus itself returns uses the OpenAI-compatible error shape: an error object with message, type, code, and — where useful — param, reason, retry_after, reset_at, request_id, and docs_url, a link to the code’s entry in the error catalog. The catalog documents every code with its cause and fix. SCIM provisioning returns SCIM error bodies instead, and errors from a provider are passed through unchanged.

{
  "error": {
    "message": "Quota exceeded: 1,000,000 input tokens per day.",
    "type": "rate_limit_error",
    "code": "policy.quota_exceeded",
    "reset_at": "2025-01-02T00:00:00Z",
    "request_id": "req_8f3a"
  }
}