Docs / Gateway API
// THE DISPATCH SURFACE
Gateway API
The /v1/* surface is OpenAI-wire-compatible: your existing client works unchanged once you point base_url at your gateway. Every dispatch is routed, guarded, budgeted, and stamped with a verifiable receipt whose hash comes back in a response header.
https://agentics.you/api/v1. Authenticate with a gateway key (ak_…) as a bearer token, exactly like any OpenAI-compatible endpoint.
Dispatch endpoints
The primary surface. Accepts the standard chat-completions body; supports stream:true. Streamed responses are tee'd so the gateway can hash and guard the output without breaking the stream. Returns one billable=true parent receipt.
Embeddings dispatch. Same routing, budgeting, and receipt semantics as chat — useful when you want spend and provenance over a retrieval pipeline, not just generation.
Lists the models and provider @slugs available to your tenant under its current config. Use the returned ids directly in the model field.
Selecting a provider
Address a specific upstream with an @provider/model slug, or pass a bare model id and let your routing config resolve it. The slug is chain-agnostic and provider-named — it is part of the receipt body, so the model a call actually used is itself tamper-evident.
// pin a provider + model explicitly
"model": "@anthropic/claude-opus-4-8"
// or pass a bare id and let routing/fallback decide the upstream
"model": "claude-opus-4-8"Request & receipt headers
| Header | Direction | Meaning |
|---|---|---|
| Authorization | request | Bearer ak_… — your gateway key. Keep it server-side. |
| x-agentics-user | request | End-user / actor identifier, recorded for attribution. Set it via create_headers(user=…). |
| x-agentics-metadata | request | Optional JSON of routing tags (e.g. cost_center) used by conditional routing and chargeback. |
| x-agentics-receipt | response | The receipt_hash of the parent receipt for this request. Copy it and verify it — or fold it on your own machine. |
| x-agentics-decision | response | allow | block | escalate — the inline policy verdict, itself receipted. |
The fixed middleware order
Every request runs the same pipeline before and after the provider call. The order is fixed so behavior is predictable and every step is receiptable:
- Resolve provider — the
@slugor your config picks the upstream. - Route — fallback / load-balance / conditional routing applies.
- Input guardrails + budget pre-check — redaction, policy, and Spend Guard run before a token reaches the provider.
- Provider call — streamed responses are tee'd for hashing and guarding.
- Output guardrails — checks on the response.
- Param shaping — drop or default params per config.
- Inline receipt write — one
billable=trueparent receipt,prev_hash-chained.
Error model
Errors return a JSON body with a stable code and a human message. A policy block is not a transport error — it returns 200 with outcome: "blocked" and a receipt, because the block is itself an auditable event.
| Status | code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing or invalid gateway key. |
| 402 | budget_exceeded | A Spend Guard hard-stop fired before dispatch. Receipted with outcome: "blocked". |
| 404 | model_not_found | The model / @slug isn't available to this tenant. |
| 429 | rate_limited | Provider or tenant rate limit. Honor Retry-After. |
| 502 | provider_error | Upstream failed after routing/fallback exhausted. Receipted with outcome: "failed". |