API ReferenceGateway

Create response

Send a response request through the Respan gateway using the OpenAI Responses API format. Supports streaming, tool use, and prompt management.

Respan parameters can be passed the same way as Create chat completion: top-level fields, nested under respan_params, or via X-Respan-Params header.

Headers

AuthorizationstringRequired

Bearer token. Use Bearer YOUR_API_KEY.

X-Respan-BetastringOptional

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

Request

This endpoint expects an object.
modelstringRequired
Model to use.
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 credential overrides per provider.

cache_enabledbooleanOptional
Enable response caching.
cache_ttlintegerOptional
Cache TTL in seconds.
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 objectsOptional
Load balancing model list.
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.
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.

Response

Model response

Errors

400
Bad Request Error
401
Unauthorized Error