Create a model response
POST/v1/responses
OpenAI-compatible Responses API.
DVARA translates the request into its model-call contract and applies
the same configured policy, PII, guardrail, budget, routing, usage,
cost, and audit controls as Chat Completions. Non-streaming requests can
use the response cache; streams bypass it. Set stream: true for typed
SSE events. Observational response controls preserve incremental
delivery, while a control that can withhold output holds the complete
response before release or refusal. response.completed carries the
usage when the provider reports it; DVARA estimates usage for its own
records otherwise.
Text and image input, instructions, structured output through
text.format, and your own tools are honored. Tools can be function
tools (with tool_choice), custom tools, namespace tools, and a
tool search your client runs. DVARA runs no tool; your code does.
Features that need state or run at the provider are refused with
unsupported_capability (HTTP 400), never silently dropped:
| Refused request | Why |
|---|---|
Built-in tools: web_search, file_search, code_interpreter, computer_use, image_generation, mcp | They run at the provider, outside DVARA's checks. |
store: true, previous_response_id | The gateway is stateless. Send the full input each turn with store: false. |
background: true, reusable prompt objects | They need state at the provider. Use DVARA prompt templates instead of prompt. |
A service_tier other than auto or default | It changes the price and speed of the call. |
An include value other than reasoning.encrypted_content | The requested output would be absent from the response. |
A reasoning key other than effort, summary, generate_summary or context | Not supported. |
input parts of type input_file / input_audio | Text and image input only. |
An input item of a type DVARA does not read | It would reach the model as an empty turn. |
| A tool type DVARA cannot translate, on a provider other than OpenAI or Azure OpenAI | Only those two providers' own Responses API is sent such a tool as-is. |
Both /v1/responses and /v1/chat/completions are stateless — send
the full input on each turn.
Request
Responses
- 200
- 400
- 401
- 402
- 403
- 413
- 422
- 429
- 500
- 502
- 503
Response object, or an SSE stream of typed events when stream=true
The request was refused before dispatch: a body that is not valid JSON or has a field of the wrong type (invalid_json), a body that fails validation (validation_error, with the field names in param), an invalid body (invalid_request), no provider for the model (no_provider, no_capable_provider), an unsupported field or capability (unsupported_capability, unsupported_response_format), a request too large for the model's context window (context_window_exceeded), a PII BLOCK action (pii_detected), or the provider refused the request itself (provider_rejected_request).
No key was sent (api_key_required), or the key is unknown (invalid_api_key), revoked (api_key_revoked) or expired (api_key_expired).
A hard budget cap is exhausted (budget_cap_hard), the call would cost more than the per-call ceiling (per_call_cost_exceeded), or, without a licence, the monthly call band is used up (license_token_cap_exceeded, type token_cap_exceeded).
The key's nonempty scope list does not cover the operation (api_key_scope; chat, Responses, completions and the Cursor route need completions:write, embeddings need embeddings:write); a policy rule (policy_denied), guardrail (guardrail_blocked, hallucination_detected, grounding_unavailable), IP rule (IP_ACCESS_DENIED, in upper case, Enterprise platform) or data-residency rule (data_residency_violation) refused the call; PII tokenization or redaction was needed but unavailable (pii_tokenize_unavailable, pii_redact_unavailable); or the workspace is suspended (workspace_suspended) or must use its own provider credential (workspace_credential_required). A PII BLOCK is 400 pii_detected instead.
The input is over a configured guardrail size limit (input_too_large), such as messages per request, message length or input tokens.
The model's answer did not match the configured output schema (schema_validation_failed).
The key's rate limit is reached (rate_limit_exceeded, with a Retry-After header), priority admission control throttled the request (priority_throttled), or the provider is rate limiting the call (provider_rate_limited, with Retry-After when the provider gave one).
Response Headers
Seconds to wait before retrying, when known.
A configured guardrail plugin failed (guardrail_plugin_error), the key has no id in the gateway's configuration (api_key_misconfigured), or an unexpected error happened in the gateway (internal_error, type gateway_error).
Every configured provider on the route (and every fallback) has failed.
The provider's circuit breaker is open (provider_circuit_open), no fallback provider can serve what the request needs (failover_capability_mismatch), or the workspace's own provider credential cannot be read (workspace_credential_unavailable). On the Enterprise platform, a gateway that cannot store audit events refuses every call with audit_store_full (type service_unavailable) and a Retry-After: 30 header until it can.