Gateway API

Base URLs#

For the local Node runtime:

Prefer /gateway/v1 as the SDK base URL when Gateway, API, and OTLP share one origin. It keeps model traffic distinct from Provon's control API and OTLP routes.

Production deployments replace the local origin with the public Gateway origin for that runtime.

Authentication#

Send a Provon project API key as a Bearer token:

Authorization: Bearer <PROVON_API_KEY>

Relevant API-key capabilities:

Workbench sessions use project permissions instead of these API-key capabilities.

Provider credentials are not valid Gateway client credentials. They remain attached to project-scoped Provider Keys.

First Request#

curl "$PROVON_BASE_URL/gateway/v1/chat/completions" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "x-otel-gen-ai-conversation-id: conversation-123" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

The request and response follow the selected Gateway endpoint shape. Provider adapters may translate that shape to a native upstream protocol and translate the result back.

Model Values#

Provider-qualified values are the safest integration default because provider intent is explicit. Plain names are useful when the project owns a stable logical model name. provon/auto is useful when target selection should consider request fit, health, latency, and estimated cost.

See Routing and reliability.

Request Context#

Gateway context headers become OpenTelemetry attributes on the root and attempt spans. They do not change provider routing unless a separately configured policy uses the same value.

Values are trimmed and limited to 512 characters. Use stable pseudonymous user IDs when raw identity is not required. Never send secrets in context headers.

For multi-turn diagnostics, x-otel-gen-ai-conversation-id is the most important field: Provon uses it to reconstruct a conversation across traces.

Endpoint Discovery#

Gateway recognizes these endpoint families:

chat-completions      responses             messages
embeddings            rerank                ocr
image-generations     image-edits           image-variations
audio-transcriptions  audio-speech          moderations
batches               files                 fine-tuning
vector-stores         realtime              videos
video-extensions      video-edits           search
classify              pipeline              a2a
mcp-tools

Recognition does not imply that every provider supports every family. Query the project capability matrix:

curl "$PROVON_BASE_URL/v1/gateway/capability-matrix?includeDisabled=false" \
  -H "Authorization: Bearer $PROVON_API_KEY"

The response distinguishes:

• native: the provider exposes the endpoint shape directly;
• translated: Provon adapts the Gateway shape to a provider-native endpoint;
• bridged: the public endpoint is implemented through another provider endpoint family;
• unsupported: the provider cannot serve that endpoint;
• available or disabled: project Provider Key availability.

Inspect eligible model targets for one endpoint and feature set:

curl \
  "$PROVON_BASE_URL/v1/gateway/model-selection?endpoint=chat-completions&features=streaming,tool-calling" \
  -H "Authorization: Bearer $PROVON_API_KEY"

Supported feature filters include streaming, tool calling, structured outputs, reasoning, vision, audio, prompt caching, usage metadata, native passthrough, and custom base URLs.

List the provider catalog:

curl "$PROVON_BASE_URL/v1/gateway/providers" \
  -H "Authorization: Bearer $PROVON_API_KEY"

Control API#

Project API keys with workspace:read can inspect Gateway configuration:

Keys with gateway:manage can write Provider Keys and mappings:

Signed-in Workbench routes also expose project-qualified variants under /v1/projects/:projectId/gateway/*. Prefer the unqualified paths for project API-key clients because the project is already derived from the key.

Common Inference Paths#

The explicit Gateway prefix accepts the corresponding path under /gateway/v1:

Use the capability matrix before integrating less common or provider-native paths.

Streaming#

For OpenAI-compatible streaming endpoints, send the normal request field:

{
  "model": "openai/gpt-5-mini",
  "stream": true,
  "messages": [{ "role": "user", "content": "Write one sentence." }]
}

The candidate target must declare streaming. Provon streams the provider-compatible response while collecting final attempt, usage, guardrail, and trace evidence where available.

Request IDs#

Successful and failed inference responses include x-provon-request-id after request context is established. Log this value with the application request and use it to correlate:

• the client failure;
• the Gateway root trace ID;
• upstream attempt spans;
• usage-policy and guardrail evidence.

Clients may send x-provon-request-id, but generated IDs are safer unless the caller guarantees uniqueness.

Error Shape#

Gateway-owned errors use a JSON envelope:

{
  "error": {
    "code": "GATEWAY_PAUSED",
    "message": "gateway is paused for this project",
    "details": {}
  }
}

Usage-policy rejections return 429 with Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Guardrail blocks return 409 with PROVON_GATEWAY_GUARD_TRIGGERED and guardrail headers.

Provon Cloud managed model requests return 402 with INSUFFICIENT_GATEWAY_CREDITS when the organization cannot reserve the estimated request cost. A paused project Gateway returns 503 with GATEWAY_PAUSED. Model resolution with no eligible target returns 404 with UPSTREAM_NOT_CONFIGURED.

Upstream provider errors remain provider-compatible when possible and gain normalized classification in the Gateway trace.

Transport Limits#

Runtime defaults are:

• 4 MiB for JSON request bodies;
• 25 MiB for other supported request bodies;
• no compressed Gateway request body;
• a 60-second overall Gateway request deadline;
• 2 MiB maximum response body capture for telemetry.

Deployments can override these limits. A provider may impose stricter limits.

Related Docs#

• Gateway quickstart
• Migration guide
• Integrate SDKs
• Model providers
• Routing and reliability
• Gateway governance
• Gateway evidence
• Production guide
• Gateway troubleshooting