For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DiscordPlatform
DocumentationIntegrationsAPI referenceSDKsChangelog
DocumentationIntegrationsAPI referenceSDKsChangelog
  • API Reference
      • POSTCreate chat completion
      • POSTCreate response
  • Reference
    • Filters API Reference
LogoLogo
DiscordPlatform
API ReferenceGateway

Create response

POST
https://api.respan.ai/api/responses
POST
/api/responses
$curl -X POST https://api.respan.ai/api/responses \
>     -H "Authorization: Bearer sk_live_xxxxx" \
>     -H "X-Respan-Route-Provider: vertex_ai" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "model": "gpt-4o",
>  "input": "string"
>}'
1{
2  "id": "resp_abc123",
3  "object": "response",
4  "created_at": 1709155200,
5  "model": "gpt-4o-mini",
6  "output": [
7    {
8      "type": "message",
9      "role": "assistant",
10      "content": [
11        {
12          "type": "output_text",
13          "text": "Why do programmers prefer dark mode? Because light attracts bugs!"
14        }
15      ]
16    }
17  ],
18  "usage": {
19    "input_tokens": 12,
20    "output_tokens": 18,
21    "total_tokens": 30
22  }
23}
Send a response request through the Respan gateway using the OpenAI Responses API format. Supports streaming, tool use, and prompt management. 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
Was this page helpful?
Previous

List prompts

Next
Built with

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

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

Headers

AuthorizationstringRequired

Bearer token. Use Bearer YOUR_API_KEY.

X-Data-Respan-ParamsstringOptional

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

X-Respan-Route-ProviderstringOptional

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-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. 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.

Response

Model response

Errors

400
Bad Request Error
401
Unauthorized Error