Privian
Get Started

Your first request

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

Request

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

{
  "prompt": "Email john@acme.com about Friday.",
  "model": "openai/gpt-5.5",
  "stream": false
}

Fields

  • prompt — string. Required. Max 32 KiB characters by default.
  • model — string. Required. Provider-namespaced ID from the catalog (e.g. openai/gpt-5.5, anthropic/claude-sonnet-4.5).
  • stream — boolean. Optional. Delivers the rehydrated response as text/event-stream chunks.

What Privian does

  1. Validates the API key and request shape.
  2. Deterministically detects entities in the prompt (email, phone, name, IBAN, card, JWT, provider API keys, …).
  3. Replaces each entity with a stable placeholder (EMAIL_1, PERSON_1, CREDIT_CARD_1, …).
  4. Sends the masked prompt to the selected provider.
  5. Rehydrates placeholders in the provider response.
  6. Returns the rehydrated text plus a diagnostic meta block.

Response (200 OK)

json
{
  "response": "Sent. I'll email John at john@acme.com about Friday.",
  "model": "openai/gpt-5.5",
  "meta": {
    "providerId": "litellm",
    "executionPath": "primary",
    "fallbackUsed": false,
    "timedOut": false,
    "entitiesDetected": 2,
    "latency": {
      "totalMs": 612,
      "maskingMs": 3,
      "providerMs": 601,
      "rehydrationMs": 1
    },
    "fallback": { "used": false, "reason": "not_attempted" }
  }
}

The meta block is diagnostic only. It never contains raw prompt content or raw entity values — only counts and timings.

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.

Related