Sign in
gateway

Create response with OpenAI/Azure credentials

Send an OpenAI Responses API request through Respan provider passthrough. This endpoint currently routes to OpenAI direct by default, or Azure OpenAI when X-Respan-Route-Provider: azure is set. It requires OpenAI or Azure OpenAI provider credentials configured in Settings -> Providers, or supplied with credential_override. In the API reference auth field, enter your Respan API key. Paste the OpenAI or Azure OpenAI provider token in credential_override.<model>.api_key; a Respan API key with managed credits alone is not enough for this Responses API passthrough path today.

For credit-backed gateway model calls with only a Respan API key, use POST /api/chat/completions.

Respan-specific parameters can be passed three ways:

  1. Top-level body fields - add directly to the request body
  2. Nested under respan_params - explicit namespacing to avoid conflicts
  3. Header X-Data-Respan-Params - base64-encoded JSON header

Merge order: top-level body fields > respan_params > header.

Legacy compatibility:

  • keywordsai_params is still accepted and merged into respan_params
  • X-Data-Keywordsai-Params is still accepted and auto-renamed internally
post/api/responses

Headers

Authorizationstring required

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, OpenAI or Azure OpenAI provider credentials go in Settings -> Providers or the request body credential_override field, not in this auth field.

X-Data-Respan-Paramsstring

Base64-encoded JSON object of Respan parameters. Legacy X-Data-Keywordsai-Params is still accepted.

X-Respan-Route-Providerstring

Pin the request to a specific provider without changing the model slug. Example: vertex_ai routes a claude-sonnet-4-5-20250929 request to Vertex AI Claude.

X-Respan-Betastring

Comma-separated beta feature flags. Available: token-breakdown-2026-03-26, env-scoped-integrations-2026-03-28

Request body

modelstring required

OpenAI Responses API model to use. This passthrough path supports OpenAI direct by default and Azure OpenAI with X-Respan-Route-Provider: azure; use /api/chat/completions for credit-backed gateway calls with only a Respan API key.

instructionsstring

System instructions for the model.

streamboolean

Stream the response as server-sent events.

temperaturenumber double

Sampling temperature (0-2).

max_output_tokensinteger

Maximum tokens to generate.

top_pnumber double

Nucleus sampling parameter.

toolsApiResponsesPostRequestBodyContentApplicationJsonSchemaToolsItems[]

Tools the model may call.

previous_response_idstring

ID of a previous response for multi-turn conversations.

fallback_modelsstring[]

Backup models if the primary model fails.

customer_credentialsApiResponsesPostRequestBodyContentApplicationJsonSchemaCustomerCredentials

Per-customer LLM provider credentials.

credential_overrideApiResponsesPostRequestBodyContentApplicationJsonSchemaCredentialOverride

One-off OpenAI or Azure OpenAI provider credentials for this request. This is where you paste the provider token for /api/responses. Do not put your Respan API key here. For OpenAI direct, use { "gpt-4o-mini": { "api_key": "OPENAI_API_KEY" } }. For Azure OpenAI, provide api_key, api_base, and api_version for the Azure-routed model.

cache_enabledboolean

Enable response caching.

cache_ttlinteger

Cache TTL in seconds. Default: 30 days.

load_balance_groupApiResponsesPostRequestBodyContentApplicationJsonSchemaLoadBalanceGroup

Load balance group selection. Use {"group_id": "..."} to route through a configured group.

request_breakdownboolean

Return response metrics summary in the response body. For streaming, metrics appear in the final chunk.

promptApiResponsesPostRequestBodyContentApplicationJsonSchemaPrompt

Prompt template config. Properties: prompt_id (required), variables, version, echo. See Prompt management.

retry_paramsApiResponsesPostRequestBodyContentApplicationJsonSchemaRetryParams

Retry config. Properties: retry_enabled (boolean), num_retries, retry_after (seconds).

disable_logboolean

When true, omits input/output from the log. Metrics still recorded.

modelsstring[]

Model list for LLM router selection.

exclude_providersstring[]

Providers to exclude from routing.

exclude_modelsstring[]

Models to exclude from routing.

metadataApiResponsesPostRequestBodyContentApplicationJsonSchemaMetadata

Custom key-value metadata attached to the span.

custom_identifierstring

Indexed custom tag for fast querying.

customer_identifierstring

End user identifier for analytics and budgets.

customer_paramsApiResponsesPostRequestBodyContentApplicationJsonSchemaCustomerParams

Extended customer info. Properties: customer_identifier (required), group_identifier, name, email, period_budget, budget_duration (daily/weekly/monthly), total_budget, markup_percentage.

thread_identifierstring

Conversation thread ID.

positive_feedbackboolean

User feedback. true = liked, false = disliked.

propertiesApiResponsesPostRequestBodyContentApplicationJsonSchema

Typed metadata preserving native types.

respan_paramsApiResponsesPostRequestBodyContentApplicationJsonSchemaRespanParams

Namespaced container for all Respan parameters.

Response

Model response

GatewayCreateResponseResponse200 required

Changes