Skip to main content
POST
/
v1
/
responses
Create Response
curl --request POST \
  --url https://api.example.com/v1/responses \
  --header 'Content-Type: application/json' \
  --data '
{
  "background": true,
  "conversation": "<string>",
  "include": [
    "<unknown>"
  ],
  "input": "<string>",
  "instructions": "<string>",
  "max_output_tokens": 1,
  "max_tool_calls": 1,
  "metadata": "<unknown>",
  "model": "<string>",
  "parallel_tool_calls": true,
  "previous_response_id": "<string>",
  "prompt": "<unknown>",
  "prompt_cache_key": "<string>",
  "reasoning": "<unknown>",
  "safety_identifier": "<string>",
  "service_tier": "<string>",
  "store": true,
  "stream": true,
  "stream_options": "<unknown>",
  "temperature": 123,
  "text": "<unknown>",
  "tool_choice": "<string>",
  "tools": [
    "<unknown>"
  ],
  "top_logprobs": 1,
  "top_p": 123,
  "truncation": "<string>"
}
'
{
  "created_at": 123,
  "id": "<string>",
  "model": "<string>",
  "object": "<string>",
  "status": "<string>",
  "background": true,
  "conversation": {
    "id": "<string>"
  },
  "error": "<unknown>",
  "incomplete_details": {
    "reason": "<string>"
  },
  "instructions": "<string>",
  "max_output_tokens": 1,
  "max_tool_calls": 1,
  "metadata": "<unknown>",
  "output": [
    {
      "content": "<string>",
      "role": "<string>",
      "status": "<string>",
      "type": "<string>"
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": "<string>",
  "prompt": "<unknown>",
  "prompt_cache_key": "<string>",
  "reasoning": "<unknown>",
  "safety_identifier": "<string>",
  "service_tier": "<string>",
  "temperature": 123,
  "text": "<unknown>",
  "tool_choice": "<string>",
  "tools": [
    "<unknown>"
  ],
  "top_logprobs": 1,
  "top_p": 123,
  "truncation": "<string>",
  "usage": {
    "input_tokens": 1,
    "output_tokens": 1,
    "total_tokens": 1,
    "input_tokens_details": "<unknown>",
    "output_tokens_details": "<unknown>"
  }
}

Body

application/json

Request object for creating a response

​
background
boolean | null

Whether to process the response in the background. If true, the response will be processed asynchronously.

​
conversation

The ID of an existing conversation to add this response to, or configuration for a new conversation.

​
include
any[] | null

A list of items to include in the response output.

​
input

Input to the model. Can be a text string or an array of input items.

​
instructions
string | null

Instructions for the model on how to behave and respond.

​
max_output_tokens
integer<int32> | null

The maximum number of tokens to generate in the response output.

Required range: x >= 0
​
max_tool_calls
integer<int32> | null

The maximum number of tool calls that can be made in a single response.

Required range: x >= 0
​
metadata
any

Set of key-value pairs that can be attached to an object for storing additional information.

​
model
string | null

The model to use for generating the response (e.g., "gpt-4o", "gpt-4o-mini").

​
parallel_tool_calls
boolean | null

Whether to enable parallel tool calls. If true, the model can make multiple tool calls simultaneously.

​
previous_response_id
string | null

The ID of a previous response to continue from. Used for multi-turn interactions.

​
prompt
any

Reference to a prompt template and its variables

​
prompt_cache_key
string | null

Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the user field.

​
reasoning
any

Configuration for reasoning/chain-of-thought capabilities.

​
safety_identifier
string | null

An identifier for safety and content moderation purposes.

​
service_tier
string | null

The service tier to use for the request (e.g., "auto", "default").

​
store
boolean | null

Whether to store the conversation and response for later retrieval.

​
stream
boolean | null

Whether to stream the response back incrementally using Server-Sent Events (SSE).

​
stream_options
any

Options for configuring streaming behavior.

​
temperature
number<float> | null

Sampling temperature between 0 and 2. Higher values make output more random, lower values more focused.

​
text
any

Configuration for text output formatting and behavior.

​
tool_choice

Controls which tool the model should call. Can be "none", "auto", "required", or a specific tool.

​
tools
any[] | null

A list of tools the model may call. Each tool is a function with a name, description, and parameters.

​
top_logprobs
integer<int32> | null

Number of most likely tokens to return at each position, along with their log probabilities.

Required range: x >= 0
​
top_p
number<float> | null

Nucleus sampling parameter. The model considers tokens with top_p probability mass.

​
truncation
string | null

The truncation strategy to use when the input exceeds the model's context window.

Response

Response created successfully

A response object representing the output from a model invocation

​
created_at
integer<int64>
required

Unix timestamp (in seconds) when the response was created

​
id
string
required

Unique identifier for the response

​
model
string
required

The model used to generate the response

​
object
string
required

The object type, always "response"

​
status
string
required

The status of the response (e.g., "in_progress", "completed", "failed", "cancelled", "incomplete")

​
background
boolean | null

Whether the response was generated in the background

​
conversation
object

The ID of the conversation this response belongs to

​
error
any

Error information if the response failed

​
incomplete_details
object

Details about why the response is incomplete (if status is "incomplete")

​
instructions

Instructions provided to the model

​
max_output_tokens
integer<int32> | null

Maximum number of output tokens

Required range: x >= 0
​
max_tool_calls
integer<int32> | null

Maximum number of tool calls

Required range: x >= 0
​
metadata
any

Set of key-value pairs that can be attached to an object

​
output
object[] | null

The output items generated by the model

A structured item in the conversation, representing messages, tool calls, reasoning, and other interaction types

​
parallel_tool_calls
boolean | null

Whether parallel tool calls are enabled

​
previous_response_id
string | null

ID of the previous response

​
prompt
any

Prompt configuration

​
prompt_cache_key
string | null

Prompt cache key

​
reasoning
any

Reasoning configuration

​
safety_identifier
string | null

Safety identifier

​
service_tier
string | null

Service tier used

​
temperature
number<float> | null

Temperature sampling parameter

​
text
any

Text configuration

​
tool_choice

Tool choice configuration

​
tools
any[] | null

Tools available to the model

​
top_logprobs
integer<int32> | null

Number of top log probabilities to return

Required range: x >= 0
​
top_p
number<float> | null

Top-p sampling parameter

​
truncation
string | null

Truncation strategy

​
usage
object

Usage statistics for the API call