Create Response

POST

/v1/responses

curl --request POST \
  --url https://example.com/v1/responses \
  --header 'Content-Type: application/json' \
  --data '{ "agent": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "background": false, "conversation": "example", "include": [ "example" ], "input": "", "instructions": "example", "max_output_tokens": 1, "metadata": {}, "model": "example", "parallel_tool_calls": true, "previous_response_id": "example", "reasoning": { "effort": "none", "summary": "example" }, "reasoning_effort": "none", "service_tier": "example", "store": true, "stream": false, "temperature": 1, "text": {}, "tool_choice": "auto", "tools": [ {} ], "top_p": 1, "truncation": "disabled", "user": "example" }'

Create one Responses API-compatible agent response.

Parameters

Header Parameters

X-Admin-Key

Any of:

string

string

null

null

X-Project-ID

Any of:

string

string

null

null

Request Body^required

Media typeapplication/json

ResponsesRequest

Open Responses-compatible request body.

object

agent

Any of:

string

string format: uuid

null

null

background

Background

boolean

conversation

Any of:

string

string

>= 1 characters <= 200 characters

null

null

include

Any of:

Array<string>

Array<string>

null

null

input

Input

""

instructions

Any of:

string

string

<= 100000 characters

null

null

max_output_tokens

Any of:

integer

integer

>= 1 <= 8000

null

null

metadata

Metadata

object

key

additional properties

any

model

required

Model

string

parallel_tool_calls

Parallel Tool Calls

boolean

default: true

previous_response_id

Any of:

string

string

null

null

reasoning

Any of:

ResponsesReasoning

ResponsesReasoning

Responses-compatible reasoning controls.

object

effort

Any of:

string

string

Allowed values: none minimal low medium high xhigh

null

null

summary

Any of:

Summary

Summary

null

null

key

additional properties

any

null

null

reasoning_effort

Any of:

string

string

Allowed values: none minimal low medium high xhigh

null

null

service_tier

Any of:

string

string

>= 1 characters <= 64 characters

null

null

store

Store

boolean

default: true

stream

Stream

boolean

temperature

Any of:

number

number

<= 2

null

null

text

Any of:

object

object

key

additional properties

any

null

null

tool_choice

Any of:

Tool Choice

Tool Choice

default: auto

null

null

tools

Any of:

Array<object>

Array<object>

object

key

additional properties

any

null

null

top_p

Any of:

number

number

<= 1

null

null

truncation

Any of:

string

string

Allowed values: disabled auto

null

null

user

Any of:

string

string

>= 1 characters <= 200 characters

null

null

key

additional properties

any

Responses

200

Responses object. When request stream=true, the same object is emitted as semantic text/event-stream events.

Media typeapplication/json

ResponsesResponse

Open Responses-compatible response object.

object

created_at

required

Created At

integer

error

Any of:

object

object

key

additional properties

any

null

null

id

required

Id

string

incomplete_details

Any of:

object

object

key

additional properties

any

null

null

instructions

Any of:

string

string

null

null

metadata

Metadata

object

key

additional properties

any

model

required

Model

string

object

Object

string

default: response

Allowed value: response

output

required

Output

Array<object>

object

key

additional properties

any

previous_response_id

Any of:

string

string

null

null

reasoning

ResponsesReasoning

Responses-compatible reasoning controls.

object

effort

Any of:

string

string

Allowed values: none minimal low medium high xhigh

null

null

summary

Any of:

Summary

Summary

null

null

key

additional properties

any

status

required

Status

string

Allowed values: queued in_progress completed failed incomplete cancelled

temperature

Any of:

number

number

null

null

tools

Tools

Array<object>

object

key

additional properties

any

top_p

Any of:

number

number

null

null

usage

required

ResponsesUsage

Responses-compatible usage payload.

object

input_tokens

Input Tokens

integer

0

input_tokens_details

ResponsesUsageDetails

Responses-compatible token details.

object

cached_tokens

Cached Tokens

integer

0

output_tokens

Output Tokens

integer

0

output_tokens_details

ResponsesOutputUsageDetails

Responses-compatible output token details.

object

reasoning_tokens

Reasoning Tokens

integer

0

total_tokens

Total Tokens

integer

0

Example

{
  "object": "response",
  "reasoning": {
    "effort": "none"
  },
  "status": "queued",
  "usage": {
    "input_tokens": 0,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 0,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 0
  }
}

409

Idempotency key conflict or in-progress replay.

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

ctx

Context

object

input

Input

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Example^generated

{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}