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

# Create a response

`POST /api/responses`

Create an OpenAI-compatible response through Respan. Enter RESPAN_API_KEY in the Authorization control, choose the openai, azure, or perplexity example, and replace PROVIDER_API_KEY with that provider's key. Each example owns its fixed route-provider header and compatible request shape. The OpenAI example is otherwise ready to run. For Azure, also replace YOUR_AZURE_DEPLOYMENT and YOUR_RESOURCE; a Responses-compatible api_version is prefilled. Switching examples clears provider-specific fields left by the previous selection. Provider credentials may alternatively be stored in Settings -> Providers. Successful responses include X-Respan-Log-Id and are logged with the actual provider model and cost.

## Query parameters

- `format` 'json' | 'txt'

## Headers

- `Authorization` string, required
- `X-Respan-Route-Provider` 'openai' | 'azure' | 'perplexity'

## Request body

- object
  - `model` string — OpenAI: use a supported model such as gpt-4o-mini. Azure: use azure/<your-deployment-name>. Perplexity: use a provider-prefixed model, or omit model when using preset or models.
  - `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. May be used without model.
  - `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` ApiResponsesPostRequestBodyContentApplicationJsonSchemaResponseFormat — 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` ApiResponsesPostRequestBodyContentApplicationJsonSchemaRespanParams — 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.

## 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, preset, or models value.
- `401` — Missing or invalid Respan authentication, or no usable provider credential. Configure the provider in Settings or supply respan_params.credential_override.
- `422` — Request validation failed.

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/c26d550029f8/schema)