Get Started

Your first request

Walk through one full Chat Completions request and response and see exactly what Privian does at each step.

Request

http
POST https://api.privian.io/v1/chat/completions
Authorization: Bearer sk-gw_live_...
Content-Type: application/json

{
  "model": "openai/gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "Email john@acme.com about Friday." }
  ]
}

Fields

  • model — string. Required. Provider-namespaced ID from the catalog (e.g. openai/gpt-4o-mini, anthropic/claude-sonnet-4-5).
  • messages — array. Required. Each message has a role (system, developer, user, or assistant) and a string content.
  • temperature, top_p, max_tokens, stop, seed — optional, forwarded to the provider.

Not yet supported: stream, tools / function calling, multimodal content parts, and the Responses API. These return a fail-closed error.

What Privian does

  1. Validates the API key and request shape.
  2. Deterministically detects entities in every message (email, phone, name, IBAN, card, JWT, provider API keys, …).
  3. Replaces each entity with a stable placeholder (EMAIL_1, PERSON_1, CREDIT_CARD_1, …) shared across all messages in the request.
  4. Sends the masked messages to the selected provider.
  5. Rehydrates PII placeholders in the provider response. Secrets stay as placeholders by policy.
  6. Returns the response in the OpenAI Chat Completions envelope.

Response (200 OK)

json
{
  "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 response shape matches the OpenAI SDK so existing clients can read response.choices[0].message.content unchanged.

Headers

  • x-request-id — stable per-request identifier. Include it in bug reports.
  • Retry-After — present on 429 responses, in seconds.

Errors

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

See the API Reference for the full error table.

Legacy API

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

http
# Legacy API
POST https://api.privian.io/v1/gateway
Authorization: Bearer sk-gw_live_...
Content-Type: application/json

{
  "model": "openai/gpt-4o-mini",
  "prompt": "Email john@acme.com about Friday."
}

Related