---
title: "Create response with OpenAI/Azure credentials"
method: POST
path: "/api/responses"
tags: ["gateway"]
---

# Create response with OpenAI/Azure credentials

`POST /api/responses`

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

## Headers

- `Authorization` string, required
- `X-Data-Respan-Params` string
- `X-Respan-Route-Provider` string
- `X-Respan-Beta` string

## Request body

- object
  - `model` string, required — 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.
  - `input` union, required — Input text or array of conversation messages.
    - string
    - ApiResponsesPostRequestBodyContentApplicationJsonSchemaInputOneOf1Items[]
  - `instructions` string — System instructions for the model.
  - `stream` boolean — Stream the response as server-sent events.
  - `temperature` number, double — Sampling temperature (0-2).
  - `max_output_tokens` integer — Maximum tokens to generate.
  - `top_p` number, double — Nucleus sampling parameter.
  - `tools` ApiResponsesPostRequestBodyContentApplicationJsonSchemaToolsItems[] — Tools the model may call.
  - `previous_response_id` string — ID of a previous response for multi-turn conversations.
  - `fallback_models` string[] — Backup models if the primary model fails.
  - `customer_credentials` ApiResponsesPostRequestBodyContentApplicationJsonSchemaCustomerCredentials — Per-customer LLM provider credentials.
  - `credential_override` ApiResponsesPostRequestBodyContentApplicationJsonSchemaCredentialOverride — 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_enabled` boolean — Enable response caching.
  - `cache_ttl` integer — Cache TTL in seconds. Default: 30 days.
  - `cache_options` ApiResponsesPostRequestBodyContentApplicationJsonSchemaCacheOptions — Cache behavior options. Properties: `cache_by_customer`, `is_cached_by_model`, `omit_log`.
    - `cache_by_customer` boolean — Partition cache entries by customer identifier.
    - `is_cached_by_model` boolean — Partition cache entries by model name.
    - `omit_log` boolean — Suppress log creation for cache hits.
  - `load_balance_group` ApiResponsesPostRequestBodyContentApplicationJsonSchemaLoadBalanceGroup — Load balance group selection. Use `{"group_id": "..."}` to route through a configured group.
  - `request_breakdown` boolean — Return response metrics summary in the response body. For streaming, metrics appear in the final chunk.
  - `prompt` ApiResponsesPostRequestBodyContentApplicationJsonSchemaPrompt — Prompt template config. Properties: `prompt_id` (required), `variables`, `version`, `echo`. See [Prompt management](/docs/documentation/features/prompt-management/advanced).
  - `retry_params` ApiResponsesPostRequestBodyContentApplicationJsonSchemaRetryParams — Retry config. Properties: `retry_enabled` (boolean), `num_retries`, `retry_after` (seconds).
  - `disable_log` boolean — When `true`, omits input/output from the log. Metrics still recorded.
  - `models` string[] — Model list for LLM router selection.
  - `exclude_providers` string[] — Providers to exclude from routing.
  - `exclude_models` string[] — Models to exclude from routing.
  - `metadata` ApiResponsesPostRequestBodyContentApplicationJsonSchemaMetadata — Custom key-value metadata attached to the span.
  - `custom_identifier` string — Indexed custom tag for fast querying.
  - `customer_identifier` string — End user identifier for analytics and budgets.
  - `customer_params` ApiResponsesPostRequestBodyContentApplicationJsonSchemaCustomerParams — Extended customer info. Properties: `customer_identifier` (required), `group_identifier`, `name`, `email`, `period_budget`, `budget_duration` (`daily`/`weekly`/`monthly`), `total_budget`, `markup_percentage`.
  - `thread_identifier` string — Conversation thread ID.
  - `positive_feedback` boolean — User feedback. `true` = liked, `false` = disliked.
  - `properties` ApiResponsesPostRequestBodyContentApplicationJsonSchema — Typed metadata preserving native types.
  - `respan_params` ApiResponsesPostRequestBodyContentApplicationJsonSchemaRespanParams — Namespaced container for all Respan parameters.

## Response `200`

Model response

- GatewayCreateResponseResponse200

## Other responses

- `400` — Bad request - Invalid parameters
- `401` — Unauthorized - Missing/invalid authentication
- `500` — Upstream provider error. This commonly occurs when OpenAI or Azure OpenAI provider credentials are not configured for this Responses API passthrough endpoint.

---

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