API Reference

Privian exposes two endpoints. New integrations should use the OpenAI-compatible Chat Completions endpoint:

https://api.privian.io/v1/chat/completions

When using the OpenAI SDK, set base_url / baseURL to:

https://api.privian.io/v1

The legacy Privian endpoint https://api.privian.io/v1/gateway (with the { prompt, model } shape) remains supported for existing integrations.

Every request requires a gateway API key. Pass it as a bearer token or asx-api-key. SeeAuthentication.

Authorization: Bearer sk-gw_live_<random>

• Keys start with sk-gw_live_ (production) or sk-gw_test_ (non-production).
• Privian stores only sha256(key).
• Missing or revoked keys return 401 unauthorized.

POST to the Chat Completions URL with a JSON body.Content-Type must be application/json.

curl -sS -X POST "https://api.privian.io/v1/chat/completions" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      { "role": "user", "content": "Hello, my name is Michael" }
    ]
  }'

Legacy API example. The original Privian endpoint also remains supported:

# Legacy API
curl -sS -X POST "https://api.privian.io/v1/gateway" \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o-mini","prompt":"Hello, my name is Michael"}'

Not yet supported on either endpoint: stream, tools / function calling, multimodal content parts, and the Responses API — they return a fail-closed error. Request body is capped at 256 KB by default; oversized requests return 413 payload_too_large.

The Chat Completions endpoint returns the standard OpenAI envelope:

{
  "id": "chatcmpl-req_abc",
  "object": "chat.completion",
  "created": 1733500000,
  "model": "openai/gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Sent. I'll email John at john@acme.com about Friday."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21
  }
}

The legacy /v1/gateway endpoint returns the Privian-native shape { response, model, meta } with a diagnostic meta block. The meta block is diagnostic only and never contains raw prompt content or raw entity values.

• x-request-id — present on every response (success and error). Quote it in bug reports.
• Retry-After — present on 429 responses, in seconds.

Send a real, provider-namespaced model ID. Examples:

• openai/gpt-4o-mini
• anthropic/claude-sonnet-4-5
• google/gemini-2.5-pro

Privian supports a curated set of BYOK model providers today, with additional LiteLLM-supported providers added through the Privian model catalog. OpenAI-format compatibility does not automatically mean every LiteLLM-supported model is enabled — only models in the Privian catalog are accepted.

Unknown or disabled IDs are rejected before any provider call with400 validation reason unsupported_model.

All errors return JSON of this shape:

{ "error": { "code": "validation", "message": "unsupported_model" } }

The model namespace (e.g. openai/) determines which provider Privian calls. The relevant BYOK credential is resolved server-side from your organisation's stored credentials. Provider keys are never accepted in the request body.

On a fallback-eligible provider error (provider_timeout, provider_unavailable,provider_rate_limit) the gateway may transparently retry once against a secondary model marked fallbackEligible in the catalog. The outcome is reflected inmeta.fallbackUsed.

Streaming is not yet supported on the OpenAI-compatible Chat Completions endpoint. Sending "stream": true returns a fail-closed streaming_not_supported error. Native provider token streaming is on the roadmap.