---
title: "Create a response"
method: POST
path: "/api/responses"
tags: ["Gateway"]
---

# Create a response

`POST /api/responses`

## Request

- Base URL: `https://api.respan.ai`
- URL: `https://api.respan.ai/api/responses`
- Auth: HTTP bearer

Creates an OpenAI-compatible response through Respan. Choose the OpenAI, Azure, Perplexity, or Bedrock example. The OpenAI and Perplexity examples use Respan-managed routing when the model is available on credits; provider credentials can also be stored in Settings > Providers or supplied in respan_params.credential_override. For Azure, replace YOUR_AZURE_DEPLOYMENT, YOUR_RESOURCE and PROVIDER_API_KEY with your Azure deployment and credentials. Bedrock Responses requires your own AWS Bedrock credentials configured in Respan (BYOK); Respan credits are not supported for this route. Successful responses include X-Respan-Log-Id and are logged with the provider model and cost.

## Query parameters

- `format` 'json' | 'txt'

## Headers

- `X-Respan-Route-Provider` 'openai' | 'azure' | 'perplexity' | 'bedrock'

## Request body

- object: OpenAI Responses API request. Standard Responses fields are accepted. Perplexity extensions are accepted only when X-Respan-Route-Provider is perplexity. Respan cache controls and `customer_identifier` may be sent at the request root or under `respan_params`; nested values win when both are present.
  - `model` string: OpenAI: use a supported model such as gpt-6-luna. Azure: use azure/<your-deployment-name>. Perplexity: use a provider-prefixed model, such as perplexity/sonar, or send `models` instead. Bedrock: use a bedrock-prefixed inference profile, such as bedrock/us.openai.gpt-6.1-sol.
  - `input` union, required: Text or structured input for the response.
    - string
    - unknown[]
      - unknown
  - `stream` boolean: Return Responses API server-sent events when true.
  - `preset` string: Perplexity Agent API preset, such as `medium`. Send it with `model` or `models`: a preset alone fails Respan's model validation.
  - `models` string[]: Perplexity Agent API fallback model chain, tried in order.
  - `max_steps` integer: Maximum Perplexity agent steps.
  - `language_preference` string: Preferred response language for Perplexity Agent API.
  - `response_format` object: Perplexity Agent API structured response configuration.
  - `skills` unknown[]: Perplexity Agent API skills.
    - unknown
  - `tools` unknown[]: Response tools. Perplexity supports web_search with filters such as search_domain_filter.
    - unknown
  - `respan_params` object: Respan metadata, prompt configuration, customer identifiers, provider credentials, and other gateway parameters. route_provider_override here cannot activate the Perplexity route.
    - `credential_override` object: Request-scoped provider credentials. Named examples prefill the correct selector; keep that selector and replace only its credential values. OpenAI and Azure selectors exactly match model. Perplexity uses an empty-string selector because its credential is provider-scoped.
    - `cache_enabled` boolean: Enable response caching for this request.
    - `cache_ttl` number: Cache lifetime in seconds. A response stored without `cache_ttl` is served from the cache for at most 30 minutes.
    - `cache_options` object
      - `cache_by_customer` boolean
      - `is_cached_by_model` boolean
      - `omit_log` boolean
    - `customer_identifier` string: End-customer identifier used for logging and optional cache partitioning.
  - `cache_enabled` boolean: Enable response caching for this request.
  - `cache_ttl` number: Cache lifetime in seconds. A response stored without `cache_ttl` is served from the cache for at most 30 minutes.
  - `cache_options` object
    - `cache_by_customer` boolean
    - `is_cached_by_model` boolean
    - `omit_log` boolean
  - `customer_identifier` string: End-customer identifier used for logging and optional cache partitioning.

## Response `200`

Response object or event stream from the selected Responses upstream.

- object

## Other responses

- `400`: Invalid request, provider route configuration, or upstream provider request. Include `input` and a route-appropriate `model`, or `models` for Perplexity.
- `401`: No usable provider credential, or the provider rejected it. Configure the provider in Settings › Providers, or pass `respan_params.credential_override`.
- `403`: The API key is missing, invalid or expired.
- `422`: Request validation failed.

## Changes

- **2026-10-21** `c30bcb383ee8`: 7 breaking, 13 info
  - request body became required
  - the response property `error/code` became nullable for the status `400`
  - the response property `error/code` became nullable for the status `401`
  - the response property `error/code` became nullable for the status `422`
  - …16 more
- **2026-10-02** `b830b79cfd52`: 3 breaking, 4 info
  - the response's body type changed from no type to `object` for status `400`
  - the response's body type changed from no type to `object` for status `401`
  - the response's body type changed from no type to `object` for status `422`
  - added the non-success response with the status `403`
  - …3 more
- **2026-09-17** `6fa8242da8c2`: 1 warning, 1 info
  - deleted the `header` request parameter `Authorization`
  - the endpoint scheme security `RespanApiKey` was added to the API
- **2026-09-12** `22b868ef3f22`: 1 info
  - api operation id `create-response` removed and replaced with `gateway_createResponse`
- **2026-08-22** `b18c72975097`: 1 warning
  - the `max_steps` request property's min was set to `1.00`

[Operation history](https://skmtc.dev/keywordsai/apis/respan-api/changes/api/responses/post.md)

---

[API](https://skmtc.dev/keywordsai/apis/respan-api.md) - [All operations](https://skmtc.dev/keywordsai/apis/respan-api/llms.txt) - [OpenAPI document](https://skmtc.dev/keywordsai/apis/respan-api/revisions/900841387635?raw)