Precepta API

Quickstart

Point any OpenAI SDK at your gateway's base URL and make one governed call. Get a key from your Precepta console under Keys & budgets.

# pip install openai — only the base_url differs from OpenAI
from openai import OpenAI
client = OpenAI(base_url="https://ai.yourco.com/v1", api_key=KEY)

resp = client.chat.completions.create(
    model="auto",                # "auto" = Smart Router
    messages=[{"role": "user", "content": "hello"}],
)
print(resp.choices[0].message.content)

Authentication

Send your key as a bearer token on every request: Authorization: Bearer <key>. Keys are scoped — a consumer key can call the data-plane endpoints below; management keys additionally read and write configuration. Keys carry their own budgets and policies.

Smart Router — it's a model, not an endpoint

Set model:"auto" and the router picks the best healthy in-boundary model per request (quality vs. cost vs. latency). It appears in GET /v1/models (owned by precepta-router), just like OpenRouter's openrouter/auto. Variants: auto:cheapest, auto:best-quality — or name an exact "<endpoint>/<model>".

POSTChat completions

/v1/chat/completions — the core endpoint; /v1/inference is a branded alias. OpenAI-identical payload, governed and audited before it reaches a model.

# Request
{ "model": "auto",
  "messages": [{"role": "user", "content": "hello"}],
  "temperature": 0.3, "max_tokens": 64 }

# Response (200)
{ "id": "chatcmpl-…", "object": "chat.completion",
  "model": "ollama/llama3.2:3b",
  "choices": [{ "index": 0, "finish_reason": "stop",
    "message": {"role": "assistant", "content": "Hello!"} }],
  "usage": {"prompt_tokens": 9, "completion_tokens": 3, "total_tokens": 12},
  "precepta": {"backend_used": "ollama", "in_boundary": true,
    "policy_decision": "allow", "cache": "miss", "trace_id": "…"} }

The additive precepta block carries governance metadata (backend, policy decision, cache, redactions, trace id). OpenAI SDKs ignore unknown fields. Send "stream": true for OpenAI-style SSE.

POSTEmbeddings

/v1/embeddings — { "model": "auto", "input": "text" } (or a list). Returns the standard OpenAI embeddings shape, generated in-boundary.

POSTModerations — content screening

/v1/moderations — OpenAI-shaped screening that runs in-boundary on precepta-guard; flags prompt-injection, PII and toxicity. Use it to pre-screen untrusted input before spending a model call.

GETModels

/v1/models — the OpenAI-standard list (id / object / created / owned_by), including the Smart Router virtual models. Retrieve one with /v1/models/{id}.

Errors — one shape

{ "error": { "message": "…", "type": "forbidden | invalid_request_error | not_found | unauthenticated | unavailable", "code": "…" } }

401 no/bad key · 403 wrong scope or a policy blocked it · 404 unknown resource · 400 malformed body · 503 no healthy model.

Sovereignty

Requests only reach in-boundary models — or the specific external hosts a platform owner approved under egress settings. Nothing else leaves. Every call is policy-checked and audited, and you can replay the full governed journey of any request in Traces. A live sovereignty attestation proves your posture.