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
Request
This endpoint expects an object.
modelstringRequired
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.
inputstring or list of objectsRequired
Input text or array of conversation messages.
instructionsstringOptional
System instructions for the model.
streambooleanOptional
Stream the response as server-sent events.
temperaturedoubleOptional
Sampling temperature (0-2).
max_output_tokensintegerOptional
Maximum tokens to generate.
top_pdoubleOptional
Nucleus sampling parameter.
toolslist of objectsOptional
Tools the model may call.
previous_response_idstringOptional
ID of a previous response for multi-turn conversations.
fallback_modelslist of stringsOptional
Backup models if the primary model fails.
customer_credentialsobjectOptional
Per-customer LLM provider credentials.
credential_overrideobjectOptional
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_enabledbooleanOptional
Enable response caching.
cache_ttlintegerOptional
Cache TTL in seconds. Default: 30 days.
cache_optionsobjectOptional
Cache behavior options. Properties: cache_by_customer, is_cached_by_model, omit_log.
load_balance_groupobjectOptional
Load balance group selection. Use {"group_id": "..."} to route through a configured group.
request_breakdownbooleanOptional
Return response metrics summary in the response body. For streaming, metrics appear in the final chunk.
promptobjectOptional
Prompt template config. Properties: prompt_id (required), variables, version, echo. See Prompt management.
retry_paramsobjectOptional
Retry config. Properties: retry_enabled (boolean), num_retries, retry_after (seconds).
disable_logbooleanOptional
When true, omits input/output from the log. Metrics still recorded.
modelslist of stringsOptional
Model list for LLM router selection.
exclude_providerslist of stringsOptional
Providers to exclude from routing.
exclude_modelslist of stringsOptional
Models to exclude from routing.
metadataobjectOptional
Custom key-value metadata attached to the span.
custom_identifierstringOptional
Indexed custom tag for fast querying.
customer_identifierstringOptional
End user identifier for analytics and budgets.
customer_paramsobjectOptional
Extended customer info. Properties: customer_identifier (required), group_identifier, name, email, period_budget, budget_duration (daily/weekly/monthly), total_budget, markup_percentage.
thread_identifierstringOptional
Conversation thread ID.
positive_feedbackbooleanOptional
User feedback. true = liked, false = disliked.
propertiesobjectOptional
Typed metadata preserving native types.
respan_paramsobjectOptional
Namespaced container for all Respan parameters.
