Skip to content
Lightcone Lightcone
NorthstarPlatformPricingLogin
API Reference
Responses

Create Responses

POST/v1/responses

Create Responses

Body ParametersJSONExpand Collapse
input: string or array of object { content, role, type } or object { content, role, status, type } or object { id, content, role, 2 more } or 41 more
One of the following:
UnionMember0 = string
UnionMember1 = array of object { content, role, type } or object { content, role, status, type } or object { id, content, role, 2 more } or 41 more
One of the following:
EasyInputMessageParam = object { content, role, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

content: string or array of ResponseInputTextParam { text, type } or ResponseInputImageParam { detail, type, file_id, image_url } or ResponseInputFileParam { type, file_data, file_id, 2 more }
One of the following:
UnionMember0 = string
UnionMember1 = array of ResponseInputTextParam { text, type } or ResponseInputImageParam { detail, type, file_id, image_url } or ResponseInputFileParam { type, file_data, file_id, 2 more }
One of the following:
ResponseInputTextParam = object { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageParam = object { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" or "high" or "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id: optional string
image_url: optional string
ResponseInputFileParam = object { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data: optional string
file_id: optional string
file_url: optional string
filename: optional string
role: "user" or "assistant" or "system" or "developer"
One of the following:
"user"
"assistant"
"system"
"developer"
type: optional "message"
Message = object { content, role, status, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role.

content: array of ResponseInputTextParam { text, type } or ResponseInputImageParam { detail, type, file_id, image_url } or ResponseInputFileParam { type, file_data, file_id, 2 more }
One of the following:
ResponseInputTextParam = object { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageParam = object { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" or "high" or "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id: optional string
image_url: optional string
ResponseInputFileParam = object { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data: optional string
file_id: optional string
file_url: optional string
filename: optional string
role: "user" or "system" or "developer"
One of the following:
"user"
"system"
"developer"
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: optional "message"
ResponseOutputMessageParam = object { id, content, role, 2 more }

An output message from the model.

id: string
content: array of object { annotations, text, type, logprobs } or object { refusal, type }
One of the following:
ResponseOutputTextParam = object { annotations, text, type, logprobs }

A text output from the model.

annotations: array of AnnotationFileCitation { file_id, filename, index, type } or AnnotationURLCitation { end_index, start_index, title, 2 more } or AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } or AnnotationFilePath { file_id, index, type }
One of the following:
AnnotationFileCitation = object { file_id, filename, index, type }

A citation to a file.

file_id: string
filename: string
index: number
type: "file_citation"
AnnotationURLCitation = object { end_index, start_index, title, 2 more }

A citation for a web resource used to generate a model response.

end_index: number
start_index: number
title: string
type: "url_citation"
url: string
AnnotationContainerFileCitation = object { container_id, end_index, file_id, 3 more }

A citation for a container file used to generate a model response.

container_id: string
end_index: number
file_id: string
filename: string
start_index: number
type: "container_file_citation"
AnnotationFilePath = object { file_id, index, type }

A path to a file.

file_id: string
index: number
type: "file_path"
text: string
type: "output_text"
logprobs: optional array of Logprob { token, bytes, logprob, top_logprobs }
token: string
bytes: array of number
logprob: number
top_logprobs: array of object { token, bytes, logprob }
token: string
bytes: array of number
logprob: number
ResponseOutputRefusalParam = object { refusal, type }

A refusal from the model.

refusal: string
type: "refusal"
role: "assistant"
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "message"
ResponseFileSearchToolCallParam = object { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string
queries: array of string
status: "in_progress" or "searching" or "completed" or 2 more
One of the following:
"in_progress"
"searching"
"completed"
"incomplete"
"failed"
type: "file_search_call"
results: optional array of object { attributes, file_id, filename, 2 more }
attributes: optional map[string or number or boolean]
One of the following:
UnionMember0 = string
UnionMember1 = number
UnionMember2 = boolean
file_id: optional string
filename: optional string
score: optional number
text: optional string
ResponseComputerToolCallParam = object { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string
action: ActionClick { button, type, x, y } or ActionDoubleClick { type, x, y } or ActionDrag { path, type } or 11 more

A click action.

One of the following:
ActionClick = object { button, type, x, y }

A click action.

button: "left" or "right" or "wheel" or 2 more
One of the following:
"left"
"right"
"wheel"
"back"
"forward"
type: "click"
x: number
y: number
ActionDoubleClick = object { type, x, y }

A double click action.

type: "double_click"
x: number
y: number
ActionDrag = object { path, type }

A drag action.

path: array of object { x, y }
x: number
y: number
type: "drag"
ActionKeypress = object { keys, type }

A collection of keypresses the model would like to perform.

keys: array of string
type: "keypress"
ActionMove = object { type, x, y }

A mouse move action.

type: "move"
x: number
y: number
ActionScreenshot = object { type }

A screenshot action.

type: "screenshot"
ActionScroll = object { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number
scroll_y: number
type: "scroll"
x: number
y: number
ActionType = object { text, type }

An action to type in text.

text: string
type: "type"
ActionWait = object { type }

A wait action.

type: "wait"
ActionPointAndType = object { text, type, x, y }

Click at a position then type text.

text: string
type: "point_and_type"
x: number
y: number
ActionMouseDown = object { type, x, y }

Press and hold the left mouse button at a position.

type: "mouse_down"
x: number
y: number
ActionMouseUp = object { type, x, y }

Release the left mouse button at a position.

type: "mouse_up"
x: number
y: number
ActionKeyDown = object { keys, type }

Press and hold a key.

keys: array of string
type: "key_down"
ActionKeyUp = object { keys, type }

Release a held key.

keys: array of string
type: "key_up"
call_id: string
pending_safety_checks: array of object { id, code, message }
id: string
code: optional string
message: optional string
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "computer_call"
ComputerCallOutput = object { call_id, output, type, 3 more }

The output of a computer tool call.

call_id: string
output: object { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

type: "computer_screenshot"
file_id: optional string
image_url: optional string
type: "computer_call_output"
id: optional string
acknowledged_safety_checks: optional array of object { id, code, message }
id: string
code: optional string
message: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseFunctionWebSearchParam = object { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string
action: object { query, type, queries, sources } or ActionOpenPage { type, url } or ActionFind { pattern, type, url }

Action type "search" - Performs a web search query.

One of the following:
ActionSearch = object { query, type, queries, sources }

Action type "search" - Performs a web search query.

query: string
type: "search"
queries: optional array of string
sources: optional array of ActionSearchSource { type, url }
type: "url"
url: string
ActionOpenPage = object { type, url }

Action type "open_page" - Opens a specific URL from search results.

type: "open_page"
url: string
ActionFind = object { pattern, type, url }

Action type "find": Searches for a pattern within a loaded page.

pattern: string
type: "find"
url: string
status: "in_progress" or "searching" or "completed" or "failed"
One of the following:
"in_progress"
"searching"
"completed"
"failed"
type: "web_search_call"
ResponseFunctionToolCallParam = object { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string
call_id: string
name: string
type: "function_call"
id: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
FunctionCallOutput = object { call_id, output, type, 2 more }

The output of a function tool call.

call_id: string
output: string or array of object { text, type } or object { type, detail, file_id, image_url } or object { type, file_data, file_id, 2 more }
One of the following:
UnionMember0 = string
UnionMember1 = array of object { text, type } or object { type, detail, file_id, image_url } or object { type, file_data, file_id, 2 more }
One of the following:
ResponseInputTextContentParam = object { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageContentParam = object { type, detail, file_id, image_url }

An image input to the model.

Learn about image inputs

type: "input_image"
detail: optional "low" or "high" or "auto"
One of the following:
"low"
"high"
"auto"
file_id: optional string
image_url: optional string
ResponseInputFileContentParam = object { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data: optional string
file_id: optional string
file_url: optional string
filename: optional string
type: "function_call_output"
id: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseReasoningItemParam = object { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string
summary: array of Summary { text, type }
text: string
type: "summary_text"
type: "reasoning"
content: optional array of object { text, type }
text: string
type: "reasoning_text"
encrypted_content: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseCompactionItemParamParam = object { encrypted_content, type, id }

A compaction item generated by the v1/responses/compact API.

encrypted_content: string
type: "compaction"
id: optional string
ImageGenerationCall = object { id, result, status, type }

An image generation request made by the model.

id: string
result: string
status: "in_progress" or "completed" or "generating" or "failed"
One of the following:
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
ResponseCodeInterpreterToolCallParam = object { id, code, container_id, 3 more }

A tool call to run code.

id: string
code: string
container_id: string
outputs: array of OutputLogs { logs, type } or OutputImage { type, url }
One of the following:
OutputLogs = object { logs, type }

The logs output from the code interpreter.

logs: string
type: "logs"
OutputImage = object { type, url }

The image output from the code interpreter.

type: "image"
url: string
status: "in_progress" or "completed" or "incomplete" or 2 more
One of the following:
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call"
LocalShellCall = object { id, action, call_id, 2 more }

A tool call to run a command on the local shell.

id: string
action: object { command, env, type, 3 more }

Execute a shell command on the server.

command: array of string
env: map[string]
type: "exec"
timeout_ms: optional number
user: optional string
working_directory: optional string
call_id: string
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
LocalShellCallOutput = object { id, output, type, status }

The output of a local shell tool call.

id: string
output: string
type: "local_shell_call_output"
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ShellCall = object { action, call_id, type, 2 more }

A tool representing a request to execute one or more shell commands.

action: object { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: array of string
max_output_length: optional number
timeout_ms: optional number
call_id: string
type: "shell_call"
id: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ShellCallOutput = object { call_id, output, type, 2 more }

The streamed output items emitted by a shell tool call.

call_id: string
output: array of object { outcome, stderr, stdout }
outcome: object { type } or object { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:
OutcomeTimeout = object { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"
OutcomeExit = object { exit_code, type }

Indicates that the shell commands finished and returned an exit code.

exit_code: number
type: "exit"
stderr: string
stdout: string
type: "shell_call_output"
id: optional string
max_output_length: optional number
ApplyPatchCall = object { call_id, operation, status, 2 more }

A tool call representing a request to create, delete, or update files using diff patches.

call_id: string
operation: object { diff, path, type } or object { path, type } or object { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

One of the following:
ApplyPatchCallOperationCreateFile = object { diff, path, type }

Instruction for creating a new file via the apply_patch tool.

diff: string
path: string
type: "create_file"
ApplyPatchCallOperationDeleteFile = object { path, type }

Instruction for deleting an existing file via the apply_patch tool.

path: string
type: "delete_file"
ApplyPatchCallOperationUpdateFile = object { diff, path, type }

Instruction for updating an existing file via the apply_patch tool.

diff: string
path: string
type: "update_file"
status: "in_progress" or "completed"
One of the following:
"in_progress"
"completed"
type: "apply_patch_call"
id: optional string
ApplyPatchCallOutput = object { call_id, status, type, 2 more }

The streamed output emitted by an apply patch tool call.

call_id: string
status: "completed" or "failed"
One of the following:
"completed"
"failed"
type: "apply_patch_call_output"
id: optional string
output: optional string
McpListTools = object { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string
server_label: string
tools: array of object { input_schema, name, annotations, description }
input_schema: unknown
name: string
annotations: optional unknown
description: optional string
type: "mcp_list_tools"
error: optional string
McpApprovalRequest = object { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string
arguments: string
name: string
server_label: string
type: "mcp_approval_request"
McpApprovalResponse = object { approval_request_id, approve, type, 2 more }

A response to an MCP approval request.

approval_request_id: string
approve: boolean
type: "mcp_approval_response"
id: optional string
reason: optional string
McpCall = object { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string
arguments: string
name: string
server_label: string
type: "mcp_call"
approval_request_id: optional string
error: optional string
output: optional string
status: optional "in_progress" or "completed" or "incomplete" or 2 more
One of the following:
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
ResponseCustomToolCallOutputParam = object { call_id, output, type, id }

The output of a custom tool call from your code, being sent back to the model.

call_id: string
output: string or array of ResponseInputTextParam { text, type } or ResponseInputImageParam { detail, type, file_id, image_url } or ResponseInputFileParam { type, file_data, file_id, 2 more }
One of the following:
UnionMember0 = string
UnionMember1 = array of ResponseInputTextParam { text, type } or ResponseInputImageParam { detail, type, file_id, image_url } or ResponseInputFileParam { type, file_data, file_id, 2 more }
One of the following:
ResponseInputTextParam = object { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImageParam = object { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" or "high" or "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id: optional string
image_url: optional string
ResponseInputFileParam = object { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data: optional string
file_id: optional string
file_url: optional string
filename: optional string
type: "custom_tool_call_output"
id: optional string
ResponseCustomToolCallParam = object { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string
input: string
name: string
type: "custom_tool_call"
id: optional string
ItemReference = object { id, type }

An internal identifier for an item to reference.

id: string
type: optional "item_reference"
ResponseOutputMessage = object { id, content, role, 2 more }

An output message from the model.

id: string
content: array of object { annotations, text, type, logprobs } or object { refusal, type }
One of the following:
ResponseOutputText = object { annotations, text, type, logprobs }

A text output from the model.

annotations: array of AnnotationFileCitation { file_id, filename, index, type } or AnnotationURLCitation { end_index, start_index, title, 2 more } or AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } or AnnotationFilePath { file_id, index, type }
One of the following:
AnnotationFileCitation = object { file_id, filename, index, type }

A citation to a file.

file_id: string
filename: string
index: number
type: "file_citation"
AnnotationURLCitation = object { end_index, start_index, title, 2 more }

A citation for a web resource used to generate a model response.

end_index: number
start_index: number
title: string
type: "url_citation"
url: string
AnnotationContainerFileCitation = object { container_id, end_index, file_id, 3 more }

A citation for a container file used to generate a model response.

container_id: string
end_index: number
file_id: string
filename: string
start_index: number
type: "container_file_citation"
AnnotationFilePath = object { file_id, index, type }

A path to a file.

file_id: string
index: number
type: "file_path"
text: string
type: "output_text"
logprobs: optional array of Logprob { token, bytes, logprob, top_logprobs }
token: string
bytes: array of number
logprob: number
top_logprobs: array of object { token, bytes, logprob }
token: string
bytes: array of number
logprob: number
ResponseOutputRefusal = object { refusal, type }

A refusal from the model.

refusal: string
type: "refusal"
role: "assistant"
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "message"
ResponseFileSearchToolCall = object { id, queries, status, 2 more }

The results of a file search tool call.

See the file search guide for more information.

id: string
queries: array of string
status: "in_progress" or "searching" or "completed" or 2 more
One of the following:
"in_progress"
"searching"
"completed"
"incomplete"
"failed"
type: "file_search_call"
results: optional array of object { attributes, file_id, filename, 2 more }
attributes: optional map[string or number or boolean]
One of the following:
UnionMember0 = string
UnionMember1 = number
UnionMember2 = boolean
file_id: optional string
filename: optional string
score: optional number
text: optional string
ResponseFunctionToolCall = object { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string
call_id: string
name: string
type: "function_call"
id: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseFunctionWebSearch = object { id, action, status, type }

The results of a web search tool call.

See the web search guide for more information.

id: string
action: object { query, type, queries, sources } or ActionOpenPage { type, url } or ActionFind { pattern, type, url }

Action type "search" - Performs a web search query.

One of the following:
ActionSearch = object { query, type, queries, sources }

Action type "search" - Performs a web search query.

query: string
type: "search"
queries: optional array of string
sources: optional array of ActionSearchSource { type, url }
type: "url"
url: string
ActionOpenPage = object { type, url }

Action type "open_page" - Opens a specific URL from search results.

type: "open_page"
url: string
ActionFind = object { pattern, type, url }

Action type "find": Searches for a pattern within a loaded page.

pattern: string
type: "find"
url: string
status: "in_progress" or "searching" or "completed" or "failed"
One of the following:
"in_progress"
"searching"
"completed"
"failed"
type: "web_search_call"
ResponseComputerToolCall = object { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string
action: ActionClick { button, type, x, y } or ActionDoubleClick { type, x, y } or ActionDrag { path, type } or 11 more

A click action.

One of the following:
ActionClick = object { button, type, x, y }

A click action.

button: "left" or "right" or "wheel" or 2 more
One of the following:
"left"
"right"
"wheel"
"back"
"forward"
type: "click"
x: number
y: number
ActionDoubleClick = object { type, x, y }

A double click action.

type: "double_click"
x: number
y: number
ActionDrag = object { path, type }

A drag action.

path: array of object { x, y }
x: number
y: number
type: "drag"
ActionKeypress = object { keys, type }

A collection of keypresses the model would like to perform.

keys: array of string
type: "keypress"
ActionMove = object { type, x, y }

A mouse move action.

type: "move"
x: number
y: number
ActionScreenshot = object { type }

A screenshot action.

type: "screenshot"
ActionScroll = object { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number
scroll_y: number
type: "scroll"
x: number
y: number
ActionType = object { text, type }

An action to type in text.

text: string
type: "type"
ActionWait = object { type }

A wait action.

type: "wait"
ActionPointAndType = object { text, type, x, y }

Click at a position then type text.

text: string
type: "point_and_type"
x: number
y: number
ActionMouseDown = object { type, x, y }

Press and hold the left mouse button at a position.

type: "mouse_down"
x: number
y: number
ActionMouseUp = object { type, x, y }

Release the left mouse button at a position.

type: "mouse_up"
x: number
y: number
ActionKeyDown = object { keys, type }

Press and hold a key.

keys: array of string
type: "key_down"
ActionKeyUp = object { keys, type }

Release a held key.

keys: array of string
type: "key_up"
call_id: string
pending_safety_checks: array of object { id, code, message }
id: string
code: optional string
message: optional string
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "computer_call"
ResponseReasoningItem = object { id, summary, type, 3 more }

A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.

id: string
summary: array of Summary { text, type }
text: string
type: "summary_text"
type: "reasoning"
content: optional array of object { text, type }
text: string
type: "reasoning_text"
encrypted_content: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseCompactionItem = object { id, encrypted_content, type, created_by }

A compaction item generated by the v1/responses/compact API.

id: string
encrypted_content: string
type: "compaction"
created_by: optional string
ImageGenerationCall = object { id, status, type, result }

An image generation request made by the model.

id: string
status: "in_progress" or "completed" or "generating" or "failed"
One of the following:
"in_progress"
"completed"
"generating"
"failed"
type: "image_generation_call"
result: optional string
ResponseCodeInterpreterToolCall = object { id, container_id, status, 3 more }

A tool call to run code.

id: string
container_id: string
status: "in_progress" or "completed" or "incomplete" or 2 more
One of the following:
"in_progress"
"completed"
"incomplete"
"interpreting"
"failed"
type: "code_interpreter_call"
code: optional string
outputs: optional array of OutputLogs { logs, type } or OutputImage { type, url }
One of the following:
OutputLogs = object { logs, type }

The logs output from the code interpreter.

logs: string
type: "logs"
OutputImage = object { type, url }

The image output from the code interpreter.

type: "image"
url: string
LocalShellCall = object { id, action, call_id, 2 more }

A tool call to run a command on the local shell.

id: string
action: object { command, env, type, 3 more }

Execute a shell command on the server.

command: array of string
env: map[string]
type: "exec"
timeout_ms: optional number
user: optional string
working_directory: optional string
call_id: string
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "local_shell_call"
ResponseFunctionShellToolCall = object { id, action, call_id, 3 more }

A tool call that executes one or more shell commands in a managed environment.

id: string
action: object { commands, max_output_length, timeout_ms }

The shell commands and limits that describe how to run the tool call.

commands: array of string
max_output_length: optional number
timeout_ms: optional number
call_id: string
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "shell_call"
created_by: optional string
ResponseFunctionShellToolCallOutput = object { id, call_id, output, 4 more }

The output of a shell tool call that was emitted.

id: string
call_id: string
output: array of object { outcome, stderr, stdout, created_by }
outcome: object { type } or object { exit_code, type }

Indicates that the shell call exceeded its configured time limit.

One of the following:
OutputOutcomeTimeout = object { type }

Indicates that the shell call exceeded its configured time limit.

type: "timeout"
OutputOutcomeExit = object { exit_code, type }

Indicates that the shell commands finished and returned an exit code.

exit_code: number
type: "exit"
stderr: string
stdout: string
created_by: optional string
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "shell_call_output"
created_by: optional string
max_output_length: optional number
ResponseApplyPatchToolCall = object { id, call_id, operation, 3 more }

A tool call that applies file diffs by creating, deleting, or updating files.

id: string
call_id: string
operation: object { diff, path, type } or object { path, type } or object { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

One of the following:
OperationCreateFile = object { diff, path, type }

Instruction describing how to create a file via the apply_patch tool.

diff: string
path: string
type: "create_file"
OperationDeleteFile = object { path, type }

Instruction describing how to delete a file via the apply_patch tool.

path: string
type: "delete_file"
OperationUpdateFile = object { diff, path, type }

Instruction describing how to update a file via the apply_patch tool.

diff: string
path: string
type: "update_file"
status: "in_progress" or "completed"
One of the following:
"in_progress"
"completed"
type: "apply_patch_call"
created_by: optional string
ResponseApplyPatchToolCallOutput = object { id, call_id, status, 3 more }

The output emitted by an apply patch tool call.

id: string
call_id: string
status: "completed" or "failed"
One of the following:
"completed"
"failed"
type: "apply_patch_call_output"
created_by: optional string
output: optional string
McpCall = object { id, arguments, name, 6 more }

An invocation of a tool on an MCP server.

id: string
arguments: string
name: string
server_label: string
type: "mcp_call"
approval_request_id: optional string
error: optional string
output: optional string
status: optional "in_progress" or "completed" or "incomplete" or 2 more
One of the following:
"in_progress"
"completed"
"incomplete"
"calling"
"failed"
McpListTools = object { id, server_label, tools, 2 more }

A list of tools available on an MCP server.

id: string
server_label: string
tools: array of object { input_schema, name, annotations, description }
input_schema: unknown
name: string
annotations: optional unknown
description: optional string
type: "mcp_list_tools"
error: optional string
McpApprovalRequest = object { id, arguments, name, 2 more }

A request for human approval of a tool invocation.

id: string
arguments: string
name: string
server_label: string
type: "mcp_approval_request"
ResponseCustomToolCall = object { call_id, input, name, 2 more }

A call to a custom tool created by the model.

call_id: string
input: string
name: string
type: "custom_tool_call"
id: optional string
background: optional boolean
cache_salt: optional string

If specified, the prefix cache will be salted with the provided string to prevent an attacker to guess prompts in multi-user environments. The salt should be random, protected from access by 3rd parties, and long enough to be unpredictable (e.g., 43 characters base64-encoded, corresponding to 256 bit).

enable_response_messages: optional boolean

Dictates whether or not to return messages as part of the response object. Currently only supported fornon-background and gpt-oss only.

include: optional array of "code_interpreter_call.outputs" or "computer_call_output.output.image_url" or "file_search_call.results" or 3 more
One of the following:
"code_interpreter_call.outputs"
"computer_call_output.output.image_url"
"file_search_call.results"
"message.input_image.image_url"
"message.output_text.logprobs"
"reasoning.encrypted_content"
include_stop_str_in_output: optional boolean
instructions: optional string
logit_bias: optional map[number]
max_output_tokens: optional number
max_tool_calls: optional number
metadata: optional map[string]
mm_processor_kwargs: optional map[unknown]

Additional kwargs to pass to the HF processor.

model: optional string
parallel_tool_calls: optional boolean
previous_input_messages: optional array of Message { author, channel, content, 2 more } or map[unknown]
One of the following:
Message = object { author, channel, content, 2 more }
author: object { role, name }
role: "user" or "assistant" or "system" or 2 more

The role of a message author (mirrors chat::Role).

One of the following:
"user"
"assistant"
"system"
"developer"
"tool"
name: optional string
channel: optional string
content: optional array of unknown
content_type: optional string
recipient: optional string
UnionMember1 = map[unknown]
previous_response_id: optional string
priority: optional number

The priority of the request (lower means earlier handling; default: 0). Any priority other than 0 will raise an error if the served model does not use priority scheduling.

prompt: optional object { id, variables, version }

Reference to a prompt template and its variables. Learn more.

id: string
variables: optional map[string or object { text, type } or object { detail, type, file_id, image_url } or object { type, file_data, file_id, 2 more } ]
One of the following:
UnionMember0 = string
ResponseInputText = object { text, type }

A text input to the model.

text: string
type: "input_text"
ResponseInputImage = object { detail, type, file_id, image_url }

An image input to the model.

Learn about image inputs.

detail: "low" or "high" or "auto"
One of the following:
"low"
"high"
"auto"
type: "input_image"
file_id: optional string
image_url: optional string
ResponseInputFile = object { type, file_data, file_id, 2 more }

A file input to the model.

type: "input_file"
file_data: optional string
file_id: optional string
file_url: optional string
filename: optional string
version: optional string
prompt_cache_key: optional string

A key that was used to read from or write to the prompt cache.Note: This field has not been implemented yet and vLLM will ignore it.

reasoning: optional object { effort, generate_summary, summary }

gpt-5 and o-series models only

Configuration options for reasoning models.

effort: optional "none" or "minimal" or "low" or 3 more
One of the following:
"none"
"minimal"
"low"
"medium"
"high"
"xhigh"
generate_summary: optional "auto" or "concise" or "detailed"
One of the following:
"auto"
"concise"
"detailed"
summary: optional "auto" or "concise" or "detailed"
One of the following:
"auto"
"concise"
"detailed"
request_id: optional string

The request_id related to this request. If the caller does not set it, a random_uuid will be generated. This id is used through out the inference process and return in response.

service_tier: optional "auto" or "default" or "flex" or 2 more
One of the following:
"auto"
"default"
"flex"
"scale"
"priority"
skip_special_tokens: optional boolean
store: optional boolean
stream: optional boolean
temperature: optional number
text: optional object { format, verbosity }

Configuration options for a text response from the model.

Can be plain text or structured JSON data. Learn more:

format: optional object { type } or object { name, schema, type, 2 more } or object { type }

Default response format. Used to generate text responses.

One of the following:
ResponseFormatText = object { type }

Default response format. Used to generate text responses.

type: "text"
ResponseFormatTextJsonSchemaConfig = object { name, schema, type, 2 more }

JSON Schema response format.

Used to generate structured JSON responses. Learn more about Structured Outputs.

name: string
schema: map[unknown]
type: "json_schema"
description: optional string
strict: optional boolean
ResponseFormatJsonObject = object { type }

JSON object response format.

An older method of generating JSON responses. Using json_schema is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.

type: "json_object"
verbosity: optional "low" or "medium" or "high"
One of the following:
"low"
"medium"
"high"
tool_choice: optional "none" or "auto" or "required" or object { mode, tools, type } or object { type } or 2 more

Constrains the tools available to the model to a pre-defined set.

One of the following:
UnionMember0 = "none" or "auto" or "required"
One of the following:
"none"
"auto"
"required"
ToolChoiceAllowed = object { mode, tools, type }

Constrains the tools available to the model to a pre-defined set.

mode: "auto" or "required"
One of the following:
"auto"
"required"
tools: array of map[unknown]
type: "allowed_tools"
ToolChoiceTypes = object { type }

Indicates that the model should use a built-in tool to generate a response. Learn more about built-in tools.

type: "computer_use_preview"
ToolChoiceFunction = object { name, type }

Use this option to force the model to call a specific function.

name: string
type: "function"
ToolChoiceCustom = object { name, type }

Use this option to force the model to call a specific custom tool.

name: string
type: "custom"
tools: optional array of object { name, type, description, 2 more } or object { name, type, description, format } or object { display_height, display_width, environment, type }
One of the following:
FunctionTool = object { name, type, description, 2 more }

Defines a function in your own code the model can choose to call.

Learn more about function calling.

name: string
type: "function"
description: optional string
parameters: optional map[unknown]
strict: optional boolean
CustomTool = object { name, type, description, format }

A custom tool that processes input using a specified format.

Learn more about custom tools

name: string
type: "custom"
description: optional string
format: optional object { type } or object { definition, syntax, type }

Unconstrained free-form text.

One of the following:
Text = object { type }

Unconstrained free-form text.

type: "text"
Grammar = object { definition, syntax, type }

A grammar defined by the user.

definition: string
syntax: "lark" or "regex"
One of the following:
"lark"
"regex"
type: "grammar"
ComputerTool = object { display_height, display_width, environment, type }

A tool that controls a virtual computer.

Learn more about the computer tool.

display_height: number
display_width: number
environment: "windows" or "mac" or "linux" or 2 more
One of the following:
"windows"
"mac"
"linux"
"ubuntu"
"browser"
type: "computer_use_preview"
top_k: optional number
top_logprobs: optional number
top_p: optional number
truncation: optional "auto" or "disabled"
One of the following:
"auto"
"disabled"
user: optional string
ReturnsExpand Collapse
id: string
created_at: number
model: string
object: "response"
output: array of object { id, content, role, 2 more } or object { arguments, call_id, name, 3 more } or object { id, action, call_id, 3 more } or map[unknown]
One of the following:
ResponseOutputMessage = object { id, content, role, 2 more }

An output message from the model.

id: string
content: array of object { annotations, text, type, logprobs } or object { refusal, type }
One of the following:
ResponseOutputText = object { annotations, text, type, logprobs }

A text output from the model.

annotations: array of AnnotationFileCitation { file_id, filename, index, type } or AnnotationURLCitation { end_index, start_index, title, 2 more } or AnnotationContainerFileCitation { container_id, end_index, file_id, 3 more } or AnnotationFilePath { file_id, index, type }
One of the following:
AnnotationFileCitation = object { file_id, filename, index, type }

A citation to a file.

file_id: string
filename: string
index: number
type: "file_citation"
AnnotationURLCitation = object { end_index, start_index, title, 2 more }

A citation for a web resource used to generate a model response.

end_index: number
start_index: number
title: string
type: "url_citation"
url: string
AnnotationContainerFileCitation = object { container_id, end_index, file_id, 3 more }

A citation for a container file used to generate a model response.

container_id: string
end_index: number
file_id: string
filename: string
start_index: number
type: "container_file_citation"
AnnotationFilePath = object { file_id, index, type }

A path to a file.

file_id: string
index: number
type: "file_path"
text: string
type: "output_text"
logprobs: optional array of Logprob { token, bytes, logprob, top_logprobs }
token: string
bytes: array of number
logprob: number
top_logprobs: array of object { token, bytes, logprob }
token: string
bytes: array of number
logprob: number
ResponseOutputRefusal = object { refusal, type }

A refusal from the model.

refusal: string
type: "refusal"
role: "assistant"
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "message"
ResponseFunctionToolCall = object { arguments, call_id, name, 3 more }

A tool call to run a function.

See the function calling guide for more information.

arguments: string
call_id: string
name: string
type: "function_call"
id: optional string
status: optional "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
ResponseComputerToolCall = object { id, action, call_id, 3 more }

A tool call to a computer use tool.

See the computer use guide for more information.

id: string
action: ActionClick { button, type, x, y } or ActionDoubleClick { type, x, y } or ActionDrag { path, type } or 11 more

A click action.

One of the following:
ActionClick = object { button, type, x, y }

A click action.

button: "left" or "right" or "wheel" or 2 more
One of the following:
"left"
"right"
"wheel"
"back"
"forward"
type: "click"
x: number
y: number
ActionDoubleClick = object { type, x, y }

A double click action.

type: "double_click"
x: number
y: number
ActionDrag = object { path, type }

A drag action.

path: array of object { x, y }
x: number
y: number
type: "drag"
ActionKeypress = object { keys, type }

A collection of keypresses the model would like to perform.

keys: array of string
type: "keypress"
ActionMove = object { type, x, y }

A mouse move action.

type: "move"
x: number
y: number
ActionScreenshot = object { type }

A screenshot action.

type: "screenshot"
ActionScroll = object { scroll_x, scroll_y, type, 2 more }

A scroll action.

scroll_x: number
scroll_y: number
type: "scroll"
x: number
y: number
ActionType = object { text, type }

An action to type in text.

text: string
type: "type"
ActionWait = object { type }

A wait action.

type: "wait"
ActionPointAndType = object { text, type, x, y }

Click at a position then type text.

text: string
type: "point_and_type"
x: number
y: number
ActionMouseDown = object { type, x, y }

Press and hold the left mouse button at a position.

type: "mouse_down"
x: number
y: number
ActionMouseUp = object { type, x, y }

Release the left mouse button at a position.

type: "mouse_up"
x: number
y: number
ActionKeyDown = object { keys, type }

Press and hold a key.

keys: array of string
type: "key_down"
ActionKeyUp = object { keys, type }

Release a held key.

keys: array of string
type: "key_up"
call_id: string
pending_safety_checks: array of object { id, code, message }
id: string
code: optional string
message: optional string
status: "in_progress" or "completed" or "incomplete"
One of the following:
"in_progress"
"completed"
"incomplete"
type: "computer_call"
UnionMember3 = map[unknown]
status: "completed" or "failed" or "in_progress" or 2 more
One of the following:
"completed"
"failed"
"in_progress"
"incomplete"
"cancelled"
error: optional map[unknown]
tools: optional array of map[unknown]
usage: optional object { input_tokens, output_tokens, total_tokens }
input_tokens: optional number
output_tokens: optional number
total_tokens: optional number

Create Responses

curl https://api.tzafon.ai/v1/responses \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $TZAFON_API_KEY" \
    -d '{
          "input": "string"
        }'
{
  "id": "id",
  "created_at": 0,
  "model": "model",
  "object": "response",
  "output": [
    {
      "id": "id",
      "content": [
        {
          "annotations": [
            {
              "file_id": "file_id",
              "filename": "filename",
              "index": 0,
              "type": "file_citation"
            }
          ],
          "text": "text",
          "type": "output_text",
          "logprobs": [
            {
              "token": "token",
              "bytes": [
                0
              ],
              "logprob": 0,
              "top_logprobs": [
                {
                  "token": "token",
                  "bytes": [
                    0
                  ],
                  "logprob": 0
                }
              ]
            }
          ]
        }
      ],
      "role": "assistant",
      "status": "in_progress",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": {
    "foo": "bar"
  },
  "tools": [
    {
      "foo": "bar"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}
Returns Examples
{
  "id": "id",
  "created_at": 0,
  "model": "model",
  "object": "response",
  "output": [
    {
      "id": "id",
      "content": [
        {
          "annotations": [
            {
              "file_id": "file_id",
              "filename": "filename",
              "index": 0,
              "type": "file_citation"
            }
          ],
          "text": "text",
          "type": "output_text",
          "logprobs": [
            {
              "token": "token",
              "bytes": [
                0
              ],
              "logprob": 0,
              "top_logprobs": [
                {
                  "token": "token",
                  "bytes": [
                    0
                  ],
                  "logprob": 0
                }
              ]
            }
          ]
        }
      ],
      "role": "assistant",
      "status": "in_progress",
      "type": "message"
    }
  ],
  "status": "completed",
  "error": {
    "foo": "bar"
  },
  "tools": [
    {
      "foo": "bar"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  }
}