POST https://api.allocate.network/v1/chat/completions
Runs inference against a model or Route. Supports streaming, tool calls, structured output, and image, PDF, and audio inputs. Every response, including errors, carries the x-allocate-request-id header; successful responses additionally report x-allocate-overhead-ms, held to a 30ms p50 budget.
Request
Field
Type
Description
model (required)
string
A catalog model id, or the name of one of your Routes. A Route pins model, fallback chain, and policy server-side.
messages (required)
object[]
stream
boolean
When true, responds with an SSE stream of chunks terminated by [DONE]; usage arrives in the final chunk.
tools
object[]
Function tools. Streamed tool-call arguments reassemble to valid JSON.
tool_choice
any
Standard tool choice: none, auto, required, or a named function.
response_format
object
Structured output. Supports type json_schema with a schema the response must satisfy.
The completion. With stream: true, an SSE stream of chat.completion.chunk events terminated by [DONE], usage in the final chunk.
400
Malformed body or missing model field.
401
Missing, invalid, or disabled API key (type: authentication_error).
402
Billing gate: balance exhausted (type: insufficient_quota). In-flight streams are never interrupted; only new requests are gated.
403
Model policy: your organization restricts which providers may serve its prompts, and this request resolved to one outside the allowlist (type: permission_error). The policy wins over the route and the model field.
404
Unknown model id, or a Route that resolves to an unknown model (type: not_found_error).
429
Provider rate limit, passed through with its native status so client backoff behaves correctly (type: rate_limit_error). Provider detail preserved under error.native.
503
Policy check unavailable; the gateway fails closed rather than guessing about provider commitments. Retry shortly (type: api_error).
Response headers
Header
Description
x-allocate-request-id
Unique id for this request, present on every response including errors; quote it in support conversations.
x-allocate-overhead-ms
Server-reported gateway overhead for this request in milliseconds.
x-allocate-model
The model that actually served the request. Differs from the requested model only when a Route's declared fallback chain fired; fallbacks are billed at the served model's own price.
Errors
Every error uses this shape so standard SDK retry logic works unchanged. Provider detail is preserved, never substituted.
Allocate