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.

Overview

The /v1/responses endpoint implements OpenAI’s Responses API format, which differs from the Chat Completions endpoint in several ways:

Input: Accepts either a plain string or a flat array of typed input items (messages, tool calls, tool outputs)
Tools format: Flat structure {"type":"function","name":"...","description":"...","parameters":{...}} instead of the nested {"type":"function","function":{...}} used by Chat Completions
Output: Returns an output array of typed items instead of a choices array
Instructions: Supports a separate instructions field as an alternative to a system message in the input array

Use this endpoint when:

Using tools or SDKs that target the OpenAI Responses API (e.g. Codex CLI)
Building agentic workflows that pass tool calls and tool outputs in a flat item array

For general use and multi-provider support, the Chat Completions endpoint is recommended.

Authentication

Authorization: Bearer <api_key>

See the Authentication page for more details.

Request Format

model

string

required

The model ID to use, with provider prefix.Examples: openai/gpt-4o, anthropic/claude-sonnet-4-6, google/gemini-2.0-flash

input

string | array

required

The input to the model. Either:

A plain string (treated as a single user message)
An array of input items (messages, function calls, function call outputs)

Show Input item types

Message item — a regular conversation turn:

{
  "role": "user" | "assistant" | "system" | "developer",
  "content": "string or array of content parts"
}

Content can be a string or an array of typed parts:

{"type": "input_text", "text": "..."} — user input text
{"type": "output_text", "text": "..."} — assistant output text
{"type": "text", "text": "..."} — generic text part

Function call item — an assistant tool call (to include in conversation history):

{
  "type": "function_call",
  "call_id": "call_abc123",
  "name": "get_weather",
  "arguments": "{\"location\": \"Paris\"}"
}

Function call output item — the result of a tool call:

{
  "type": "function_call_output",
  "call_id": "call_abc123",
  "output": "{\"temperature\": 22}"
}

instructions

string

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

stream

boolean

default:false

Whether to stream the response as Server-Sent Events (SSE).

max_output_tokens

integer

Maximum number of tokens to generate.

tools

array

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

Show Tool object

type

string

required

Must be "function".

name

string

required

The name of the function.

description

string

Description of what the function does.

parameters

object

JSON Schema object describing the function’s parameters.

tool_choice

string | object

Controls tool selection:

"auto" — model decides whether to call a tool (default)
"none" — model must not call any tool
"required" — model must call a tool
{"type": "function", "name": "tool_name"} — model must call the specified tool

temperature

number

Sampling temperature between 0 and 2. Higher values produce more random outputs.

top_p

number

Nucleus sampling probability. Alternative to temperature.

Edgee Extensions

Response Format

Non-Streaming Response

string

Unique identifier for the response, prefixed with resp_.

object

string

Always "response".

status

string

Always "completed" for non-streaming responses.

created_at

number

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

model

string

The model used to generate the response.

output

array

Array of output items produced by the model.

Show Output item

string

Item identifier, prefixed with msg_.

type

string

"message" for text responses, "function_call" for tool calls.

status

string

Always "completed".

role

string

Always "assistant".

content

array

Array of content parts within this output item.

{"type": "output_text", "text": "..."} — text response
{"type": "function_call", "id": "...", "name": "...", "arguments": "..."} — tool call

usage

object

Token usage statistics.

Show Usage object

input_tokens

integer

Tokens in the input.

output_tokens

integer

Tokens in the output.

total_tokens

integer

Total tokens used.

Streaming Response

When stream: true, the response is sent as Server-Sent Events (SSE). Each event is a JSON object with a type field. Event sequence for a text response:

Event type	Description
`response.created`	Stream opened; initial response object with `status: "in_progress"`
`response.output_item.added`	A new output item started (message or function call)
`response.content_part.added`	A new content part started within an output item
`response.output_text.delta`	Incremental text chunk
`response.output_text.done`	Text content complete
`response.content_part.done`	Content part complete
`response.output_item.done`	Output item complete
`response.completed`	Stream complete; final response object with usage

Additional events for tool calls:

Event type	Description
`response.output_item.added`	New function call item started
`response.function_call_arguments.delta`	Incremental arguments chunk
`response.function_call_arguments.done`	Arguments complete
`response.output_item.done`	Function call item complete

Special Headers

X-Edgee-Enable-Compression

boolean

Enable token compression to reduce token usage. See Token Compression.

X-edgee-tags

string

Comma-separated list of tags for analytics and logs.Example: X-edgee-tags: production,agent,codex

X-Edgee-Debug

boolean

Enable debug mode for additional response information.

Examples

Basic Text Input

curl 'https://api.edgee.ai/v1/responses' \
  -H "Authorization: Bearer $EDGEE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-4o",
    "input": "What is the capital of France?"
  }'

With Instructions and Message Array

curl 'https://api.edgee.ai/v1/responses' \
  -H "Authorization: Bearer $EDGEE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-4o",
    "instructions": "You are a helpful assistant that responds concisely.",
    "input": [
      { "role": "user", "content": "Summarize the water cycle in one sentence." }
    ]
  }'

Streaming

curl 'https://api.edgee.ai/v1/responses' \
  -H "Authorization: Bearer $EDGEE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-4o",
    "stream": true,
    "input": "Write a short poem about the ocean."
  }'

With Tools

curl 'https://api.edgee.ai/v1/responses' \
  -H "Authorization: Bearer $EDGEE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-4o",
    "input": "What is the weather in Paris?",
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name"
            }
          },
          "required": ["location"]
        }
      }
    ]
  }'

Multi-Turn with Tool Results

curl 'https://api.edgee.ai/v1/responses' \
  -H "Authorization: Bearer $EDGEE_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "openai/gpt-4o",
    "input": [
      { "role": "user", "content": "What is the weather in Paris?" },
      {
        "type": "function_call",
        "call_id": "call_abc123",
        "name": "get_weather",
        "arguments": "{\"location\": \"Paris\"}"
      },
      {
        "type": "function_call_output",
        "call_id": "call_abc123",
        "output": "{\"temperature\": 22, \"condition\": \"sunny\"}"
      }
    ],
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          },
          "required": ["location"]
        }
      }
    ]
  }'

Error Handling

See the Errors page for details on error responses.

Chat Completions — OpenAI-compatible endpoint for multi-provider support
Anthropic Messages — Native Anthropic Messages API format

Gateway API

Console API

Overview

Authentication

Request Format

Edgee Extensions

Response Format

Non-Streaming Response

Streaming Response

Special Headers

Examples

Basic Text Input

With Instructions and Message Array

Streaming

With Tools

Multi-Turn with Tool Results

Error Handling

Gateway API

Console API

​Overview

​Authentication

​Request Format

​Edgee Extensions

​Response Format

​Non-Streaming Response

​Streaming Response

​Special Headers

​Examples

​Basic Text Input

​With Instructions and Message Array

​Streaming

​With Tools

​Multi-Turn with Tool Results

​Error Handling

​Related Endpoints

Overview

Authentication

Request Format

Edgee Extensions

Response Format

Non-Streaming Response

Streaming Response

Special Headers

Examples

Basic Text Input

With Instructions and Message Array

Streaming

With Tools

Multi-Turn with Tool Results

Error Handling

Related Endpoints