Create Response

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>"
}
'

import requests

url = "https://api.example.com/v1/responses"

payload = {
    "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>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://api.example.com/v1/responses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/responses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/responses"

	payload := strings.NewReader("{\n  \"background\": true,\n  \"conversation\": \"<string>\",\n  \"include\": [\n    \"<unknown>\"\n  ],\n  \"input\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 1,\n  \"max_tool_calls\": 1,\n  \"metadata\": \"<unknown>\",\n  \"model\": \"<string>\",\n  \"parallel_tool_calls\": true,\n  \"previous_response_id\": \"<string>\",\n  \"prompt\": \"<unknown>\",\n  \"prompt_cache_key\": \"<string>\",\n  \"reasoning\": \"<unknown>\",\n  \"safety_identifier\": \"<string>\",\n  \"service_tier\": \"<string>\",\n  \"store\": true,\n  \"stream\": true,\n  \"stream_options\": \"<unknown>\",\n  \"temperature\": 123,\n  \"text\": \"<unknown>\",\n  \"tool_choice\": \"<string>\",\n  \"tools\": [\n    \"<unknown>\"\n  ],\n  \"top_logprobs\": 1,\n  \"top_p\": 123,\n  \"truncation\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/responses")
  .header("Content-Type", "application/json")
  .body("{\n  \"background\": true,\n  \"conversation\": \"<string>\",\n  \"include\": [\n    \"<unknown>\"\n  ],\n  \"input\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 1,\n  \"max_tool_calls\": 1,\n  \"metadata\": \"<unknown>\",\n  \"model\": \"<string>\",\n  \"parallel_tool_calls\": true,\n  \"previous_response_id\": \"<string>\",\n  \"prompt\": \"<unknown>\",\n  \"prompt_cache_key\": \"<string>\",\n  \"reasoning\": \"<unknown>\",\n  \"safety_identifier\": \"<string>\",\n  \"service_tier\": \"<string>\",\n  \"store\": true,\n  \"stream\": true,\n  \"stream_options\": \"<unknown>\",\n  \"temperature\": 123,\n  \"text\": \"<unknown>\",\n  \"tool_choice\": \"<string>\",\n  \"tools\": [\n    \"<unknown>\"\n  ],\n  \"top_logprobs\": 1,\n  \"top_p\": 123,\n  \"truncation\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/responses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"background\": true,\n  \"conversation\": \"<string>\",\n  \"include\": [\n    \"<unknown>\"\n  ],\n  \"input\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 1,\n  \"max_tool_calls\": 1,\n  \"metadata\": \"<unknown>\",\n  \"model\": \"<string>\",\n  \"parallel_tool_calls\": true,\n  \"previous_response_id\": \"<string>\",\n  \"prompt\": \"<unknown>\",\n  \"prompt_cache_key\": \"<string>\",\n  \"reasoning\": \"<unknown>\",\n  \"safety_identifier\": \"<string>\",\n  \"service_tier\": \"<string>\",\n  \"store\": true,\n  \"stream\": true,\n  \"stream_options\": \"<unknown>\",\n  \"temperature\": 123,\n  \"text\": \"<unknown>\",\n  \"tool_choice\": \"<string>\",\n  \"tools\": [\n    \"<unknown>\"\n  ],\n  \"top_logprobs\": 1,\n  \"top_p\": 123,\n  \"truncation\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

POST

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>"
}
'

import requests

url = "https://api.example.com/v1/responses"

payload = {
    "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>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
  })
};

fetch('https://api.example.com/v1/responses', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/responses",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/responses"

	payload := strings.NewReader("{\n  \"background\": true,\n  \"conversation\": \"<string>\",\n  \"include\": [\n    \"<unknown>\"\n  ],\n  \"input\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 1,\n  \"max_tool_calls\": 1,\n  \"metadata\": \"<unknown>\",\n  \"model\": \"<string>\",\n  \"parallel_tool_calls\": true,\n  \"previous_response_id\": \"<string>\",\n  \"prompt\": \"<unknown>\",\n  \"prompt_cache_key\": \"<string>\",\n  \"reasoning\": \"<unknown>\",\n  \"safety_identifier\": \"<string>\",\n  \"service_tier\": \"<string>\",\n  \"store\": true,\n  \"stream\": true,\n  \"stream_options\": \"<unknown>\",\n  \"temperature\": 123,\n  \"text\": \"<unknown>\",\n  \"tool_choice\": \"<string>\",\n  \"tools\": [\n    \"<unknown>\"\n  ],\n  \"top_logprobs\": 1,\n  \"top_p\": 123,\n  \"truncation\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/v1/responses")
  .header("Content-Type", "application/json")
  .body("{\n  \"background\": true,\n  \"conversation\": \"<string>\",\n  \"include\": [\n    \"<unknown>\"\n  ],\n  \"input\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 1,\n  \"max_tool_calls\": 1,\n  \"metadata\": \"<unknown>\",\n  \"model\": \"<string>\",\n  \"parallel_tool_calls\": true,\n  \"previous_response_id\": \"<string>\",\n  \"prompt\": \"<unknown>\",\n  \"prompt_cache_key\": \"<string>\",\n  \"reasoning\": \"<unknown>\",\n  \"safety_identifier\": \"<string>\",\n  \"service_tier\": \"<string>\",\n  \"store\": true,\n  \"stream\": true,\n  \"stream_options\": \"<unknown>\",\n  \"temperature\": 123,\n  \"text\": \"<unknown>\",\n  \"tool_choice\": \"<string>\",\n  \"tools\": [\n    \"<unknown>\"\n  ],\n  \"top_logprobs\": 1,\n  \"top_p\": 123,\n  \"truncation\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/responses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"background\": true,\n  \"conversation\": \"<string>\",\n  \"include\": [\n    \"<unknown>\"\n  ],\n  \"input\": \"<string>\",\n  \"instructions\": \"<string>\",\n  \"max_output_tokens\": 1,\n  \"max_tool_calls\": 1,\n  \"metadata\": \"<unknown>\",\n  \"model\": \"<string>\",\n  \"parallel_tool_calls\": true,\n  \"previous_response_id\": \"<string>\",\n  \"prompt\": \"<unknown>\",\n  \"prompt_cache_key\": \"<string>\",\n  \"reasoning\": \"<unknown>\",\n  \"safety_identifier\": \"<string>\",\n  \"service_tier\": \"<string>\",\n  \"store\": true,\n  \"stream\": true,\n  \"stream_options\": \"<unknown>\",\n  \"temperature\": 123,\n  \"text\": \"<unknown>\",\n  \"tool_choice\": \"<string>\",\n  \"tools\": [\n    \"<unknown>\"\n  ],\n  \"top_logprobs\": 1,\n  \"top_p\": 123,\n  \"truncation\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>"
  }
}

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

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

null | object

The ID of the conversation this response belongs to

Show child attributes

error

any

Error information if the response failed

incomplete_details

null | object

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

Show child attributes

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

Show child attributes

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

null | object

Usage statistics for the API call

Show child attributes

Overview

SDKs

API Reference

Body

Response