Skip to content
LLM Router
Gateway API

OpenAI Responses

Create responses using the OpenAI Responses API format

POST/v1/responses

Creates a response using the OpenAI Responses API format (POST /v1/responses). This endpoint is compatible with OpenAI's Responses API, making it easy to use with tools like the Codex CLI.

The Gateway exposes POST /v1/responses, not the full OpenAI response storage or conversation-management API. Native provider features may pass through when the destination supports them. Cross-format routing preserves the shared message/tool representation, including freeform and namespaced tool declarations, but may omit provider-only input items and grammar constraints.

Create a response in OpenAI Responses format. Input can be text or typed items; tools use the flat Responses format. Only POST /v1/responses is exposed: the Gateway does not expose response retrieval, deletion or conversation-management routes. Native dispatch preserves provider-specific JSON fields when the destination supports the caller’s format. Cross-format routing converts through the Gateway’s shared representation: provider-only features are not guaranteed to survive. Support for reasoning, images, built-in tools and structured outputs depends on the destination model.

POSThttps://edgee.io/v1/responses

Try this endpoint

Configure your request, then run the curl command in your terminal or send it from this page.

Comma-separated analytics tags. Trimmed and merged with body tags.

Enable debug capture for this request. Does not add a debug object to the API response.

Turn tool-result trimming on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

Turn MCP tool surface reduction on or off. The threshold and resolver mode still come from the API key. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

Turn output brevity on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

Session identifier used to group request usage.

Run in your terminal

Set EDGEE_API_KEY to your Gateway API key in your terminal, then copy and run this command. Gateway requests may consume credits.

curl
curl --include --no-buffer --globoff --request POST 'https://edgee.io/v1/responses' \
  --header "Authorization: Bearer $EDGEE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "model": "openai/gpt-5.2",
  "input": "Hello!",
  "max_output_tokens": 256
}'
Send from browser

Your request is relayed through the Edgee documentation server to the Gateway. Your key is used only for this request and is not stored.

Authentication

Use an Edgee Gateway API key. Send it as Authorization: Bearer <key>.

Parameters

X-Edgee-Tagsheader · string

Comma-separated analytics tags. Trimmed and merged with body tags.

X-Edgee-Debugheader · string

Enable debug capture for this request. Does not add a debug object to the API response.

X-Edgee-Compression-Tool-Result-Trimmingheader · string

Turn tool-result trimming on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

X-Edgee-Compression-Tool-Surface-Reductionheader · string

Turn MCP tool surface reduction on or off. The threshold and resolver mode still come from the API key. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

X-Edgee-Compression-Brevityheader · string

Turn output brevity on or off. Overrides the API key setting for this request only. Values are case-insensitive, and a missing or invalid value keeps the key's setting.

X-Edgee-Session-Idheader · string

Session identifier used to group request usage.

Request body

Native dispatch preserves provider-specific JSON fields when the destination supports the caller’s format. Cross-format routing converts through the Gateway’s shared representation: provider-only features are not guaranteed to survive. Support for reasoning, images, built-in tools and structured outputs depends on the destination model.

modelstringrequired

Model identifier from GET /v1/models, in author/model format, or a configured global alias. Append :provider to request a specific provider route. Available models and providers depend on your key and organization policies.

inputunionrequired

The input to the model. Either a plain string (treated as a single user message) or a flat array of typed input items (messages, function calls, function call outputs).

Show schema
Option 1
string
Option 2

Typed input items understood by the shared converter. additional_tools supplies inline tool declarations. Native Responses accepts further item types. On cross-format conversion unrecognized items (including replayed reasoning/computer items) are skipped; do not assume provider-only conversation state is portable.

Option 1
rolestringrequired

The role of the message author.

Values: user, assistant, system, developer
contentunion

Message content. Either a plain string or an array of typed content parts.

Show schema
Option 1
string
Option 2
Option 1
typestringrequired
Values: input_text
textstringrequired
Option 2
typestringrequired
Values: output_text
textstringrequired
Option 3
typestringrequired
Values: text
textstringrequired
Option 4
typestringrequired
Values: input_image
image_urlstringrequired

Image URL or data URL.

detailstring
Option 5
typestringrequired
Values: image_url
image_urlobjectrequired
Option 6

Provider-native parts are not portable across all formats.

object
Option 2
typestringrequired
Values: function_call
call_idstringrequired

Identifier linking this call to its `function_call_output`.

namestringrequired

Name of the function the assistant is calling.

argumentsstring

Arguments passed to the function, encoded as a JSON string.

Default: "{}"
Option 3
typestringrequired
Values: function_call_output
call_idstringrequired

Identifier matching the `function_call` item this is responding to.

outputunionrequired

Tool result as text or multimodal content parts.

Show schema
Option 1
string
Option 2
Option 1
typestringrequired
Values: input_text
textstringrequired
Option 2
typestringrequired
Values: output_text
textstringrequired
Option 3
typestringrequired
Values: text
textstringrequired
Option 4
typestringrequired
Values: input_image
image_urlstringrequired

Image URL or data URL.

detailstring
Option 5
typestringrequired
Values: image_url
image_urlobjectrequired
Option 6

Provider-native parts are not portable across all formats.

object
Option 4
typestringrequired
Values: additional_tools
rolestring
Values: developer
toolsarray
Show schema

Function, freeform and namespaced tools are understood by the converter. Namespaces are flattened for dispatch and restored on returned function calls. Other provider-native types can pass through natively but are dropped during typed conversion.

Option 1
typestringrequired
Values: function
namestringrequired
descriptionstring
parametersobject
Option 2
typestringrequired
Values: custom
namestringrequired
descriptionstring
formatobject

Native grammar constraint. Cross-format conversion uses an input string parameter and does not enforce the grammar.

Option 3
typestringrequired
Values: namespace
namestringrequired
toolsarray
instructionsstring

System-level instruction prepended to the conversation. An alternative to including a `system` role message in the `input` array.

streamboolean

If set, the response is streamed as Server-Sent Events (SSE).

Default: false
max_output_tokensinteger

Maximum number of tokens to generate.

toolsarray

Tools available to the model. Uses the Responses API flat format (no nested `function` key).

Show schema

Function, freeform and namespaced tools are understood by the converter. Namespaces are flattened for dispatch and restored on returned function calls. Other provider-native types can pass through natively but are dropped during typed conversion.

Option 1
typestringrequired
Values: function
namestringrequired
descriptionstring
parametersobject
Option 2
typestringrequired
Values: custom
namestringrequired
descriptionstring
formatobject

Native grammar constraint. Cross-format conversion uses an input string parameter and does not enforce the grammar.

Option 3
typestringrequired
Values: namespace
namestringrequired
toolsarray
Show schema

Function, freeform and namespaced tools are understood by the converter. Namespaces are flattened for dispatch and restored on returned function calls. Other provider-native types can pass through natively but are dropped during typed conversion.

Option 1
typestringrequired
Values: function
namestringrequired
descriptionstring
parametersobject
Option 2
typestringrequired
Values: custom
namestringrequired
descriptionstring
formatobject

Native grammar constraint. Cross-format conversion uses an input string parameter and does not enforce the grammar.

Option 3
typestringrequired
Values: namespace
namestringrequired
toolsarray
tool_choiceunion

Tool selection on native Responses paths. Cross-format conversion supports modes and the shared nested function form; flat forced-function names are not preserved on every conversion path.

Show schema
Option 1

Bare-string mode. `auto` lets the model decide; `none` forbids tool calls.

auto | none | required | anystring
Option 2

Object form of a tool selection mode.

typestringrequired
Values: auto, none, any, required
Option 3

Native Responses forced-function form. The shared typed tool-choice representation uses {type:function,function:{name:...}}; the flat name is not preserved on every cross-format path.

typestringrequired
Values: function
namestringrequired

Name of the function to call.

temperaturenumber

Sampling temperature. Range and support depend on the destination model.

top_pnumber

Nucleus sampling probability. Alternative to temperature.

tagsarray

Optional tags to categorize and label the request. Useful for filtering and grouping requests in analytics and logs. Can also be sent via the `x-edgee-tags` header as a comma-separated string.

Show schema
string
enable_debugboolean

Enable request debug capture. Gateway-only field; does not add debug information to the response.

reasoningobject
Show schema
effortstring

Requested effort; common values include none, minimal, low, medium, high, xhigh and max. The supported vocabulary is model-specific. Cross-format routing maps supported values and can omit unrepresentable levels.

summarystring

Requested reasoning display: auto, concise or detailed. May be omitted on destinations that cannot represent it.

Responses

200Response created successfully

application/json

idstringrequired

Unique identifier for the response, prefixed with `resp_`.

objectstringrequired
Values: response
statusstringrequired

Shared converted responses use completed or in_progress; native responses can also report provider statuses such as incomplete or failed.

created_atnumberrequired

Unix timestamp (as a float) of when the response was created.

modelstringrequired

The model used to generate the response.

outputarrayrequired

Array of output items produced by the model.

Show schema

Each message, function call, custom tool call and reasoning item is a separate top-level output item. Native providers may return additional item types.

Option 1
typestringrequired
Values: message
idstringrequired
statusstringrequired
rolestringrequired
Values: assistant
contentarrayrequired
Show schema
typestringrequired
Values: output_text
textstringrequired
Option 2
typestringrequired
Values: function_call
idstringrequired
call_idstringrequired
namestringrequired
argumentsstringrequired
statusstringrequired
namespacestring
Option 3
typestringrequired
Values: custom_tool_call
idstringrequired
call_idstringrequired
namestringrequired
inputstringrequired
statusstringrequired
Option 4
typestringrequired
Values: reasoning
idstringrequired
summaryarrayrequired
Show schema
typestringrequired
Values: summary_text
textstringrequired
usageobjectrequired

Token usage statistics for the response.

Show schema
input_tokensintegerrequired

Tokens in the input.

output_tokensintegerrequired

Tokens in the output.

total_tokensintegerrequired

Total tokens used.

cached_input_tokensinteger

Cached input tokens on converted responses; omitted when zero. Native responses preserve provider-specific usage fields.

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "created_at": 1677652288,
  "model": "openai/gpt-5.2",
  "output": [
    {
      "id": "msg_1",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Paris"
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 8,
    "output_tokens": 1,
    "total_tokens": 9
  }
}

text/event-stream

Server-Sent Events stream. Each event is a JSON object prefixed with 'data: ' and followed by two newlines. Each event has a `type` field. Text responses produce: `response.created`, `response.output_item.added`, `response.content_part.added`, `response.output_text.delta`, `response.output_text.done`, `response.content_part.done`, `response.output_item.done`, `response.completed`. Tool calls additionally produce: `response.function_call_arguments.delta`, `response.function_call_arguments.done`. Reasoning also emits response.reasoning_summary_part.added/done and response.reasoning_summary_text.delta/done. Freeform tools emit response.custom_tool_call_input.delta/done. There is no [DONE] sentinel. Failures after headers are sent are reported inside the stream.

string
400Malformed request, invalid/disabled model or provider, or unsupported conversion.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

401Missing or invalid API credentials.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

403Key inactive, expired, model restriction or other permission failure.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

429Usage or routing-strategy budget exhausted, or provider rate limit.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

500Internal processing error.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

502Upstream provider failure.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

503Usage accounting or upstream service temporarily unavailable.

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

529Upstream provider overloaded (when preserved by the request path).

application/json

OpenAI-shaped Gateway error. Native upstream errors can retain provider-specific details.

errorobjectrequired
Show schema
messagestringrequired

A human-readable error message.

typestringrequired

High-level error category.

codestring

Machine-readable error code, for example unauthorized, invalid_json, bad_model_id, model_disabled, provider_disabled, usage_limit_exceeded, usage_unavailable, provider_error or internal_error. Not an exhaustive enum.

paramstring

Name of the request parameter that caused the error, when applicable.

Download the OpenAPI specification