Beta
BetaChatKit
ModelsExpand Collapse
ChatKitWorkflow { id, state_variables, tracing, version } Workflow metadata and state returned for the session.
Workflow metadata and state returned for the session.
BetaChatKitSessions
Cancel chat session
Create ChatKit session
BetaChatKitThreads
List ChatKit thread items
Retrieve ChatKit thread
Delete ChatKit thread
List ChatKit threads
ModelsExpand Collapse
ChatSession { id, chatkit_configuration, client_secret, 7 more } Represents a ChatKit session and its resolved configuration.
Represents a ChatKit session and its resolved configuration.
Resolved ChatKit feature configuration for the session.
ChatSessionChatKitConfigurationParam { automatic_thread_titling, file_upload, history } Optional per-session configuration settings for ChatKit behavior.
Optional per-session configuration settings for ChatKit behavior.
automatic_thread_titling?: AutomaticThreadTitling { enabled } Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.
Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default.
file_upload?: FileUpload { enabled, max_file_size, max_files } Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).
Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB).
ChatSessionWorkflowParam { id, state_variables, tracing, version } Workflow reference and overrides applied to the chat session.
Workflow reference and overrides applied to the chat session.
state_variables?: Record<string, string | boolean | number>State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object.
State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object.
ChatKitResponseOutputText { annotations, text, type } Assistant response text accompanied by optional annotations.
Assistant response text accompanied by optional annotations.
ChatKitThread { id, created_at, object, 3 more } Represents a ChatKit thread and its current status.
Represents a ChatKit thread and its current status.
status: Active { type } | Locked { reason, type } | Closed { reason, type } Current status for the thread. Defaults to active for newly created threads.
Current status for the thread. Defaults to active for newly created threads.
ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } Assistant-authored message within a thread.
Assistant-authored message within a thread.
ChatKitThreadItemList { data, first_id, has_more, 2 more } A paginated list of thread items rendered for the ChatKit API.
A paginated list of thread items rendered for the ChatKit API.
data: Array<ChatKitThreadUserMessageItem { id, attachments, content, 5 more } | ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } | ChatKitWidgetItem { id, created_at, object, 3 more } | 3 more>A list of items
A list of items
ChatKitThreadUserMessageItem { id, attachments, content, 5 more } User-authored messages within a thread.
User-authored messages within a thread.
content: Array<InputText { text, type } | QuotedText { text, type } >Ordered content elements supplied by the user.
Ordered content elements supplied by the user.
ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } Assistant-authored message within a thread.
Assistant-authored message within a thread.
ChatKitClientToolCall { id, arguments, call_id, 7 more } Record of a client side tool invocation initiated by the assistant.
Record of a client side tool invocation initiated by the assistant.
ChatKitTask { id, created_at, heading, 5 more } Task emitted by the workflow to show progress and status updates.
Task emitted by the workflow to show progress and status updates.
ChatKitThreadUserMessageItem { id, attachments, content, 5 more } User-authored messages within a thread.
User-authored messages within a thread.
content: Array<InputText { text, type } | QuotedText { text, type } >Ordered content elements supplied by the user.
Ordered content elements supplied by the user.
BetaAssistants
Build Assistants that can call models and use tools.
List assistants
Create assistant
Retrieve assistant
Modify assistant
Delete assistant
ModelsExpand Collapse
Assistant { id, created_at, description, 10 more } Represents an assistant that can call the model and use tools.
Represents an assistant that can call the model and use tools.
The description of the assistant. The maximum length is 512 characters.
The system instructions that the assistant uses. The maximum length is 256,000 characters.
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
ID of the model to use. You can use the List models API to see all of your available models, or see our Model overview for descriptions of them.
A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter, file_search, or function.
Specifies the format that the model must output. Compatible with GPT-4o, GPT-4 Turbo, and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.
Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.
Setting to { "type": "json_object" } enables JSON mode, which ensures the message the model generates is valid JSON.
Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly “stuck” request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.
What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
tool_resources?: ToolResources | nullA set of resources that are used by the assistant’s tools. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.
A set of resources that are used by the assistant’s tools. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.
code_interpreter?: CodeInterpreter { file_ids }
A list of file IDs made available to the `code_interpreter“ tool. There can be a maximum of 20 files associated with the tool.
file_search?: FileSearch { vector_store_ids }
The ID of the vector store attached to this assistant. There can be a maximum of 1 vector store attached to the assistant.
An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.
We generally recommend altering this or temperature but not both.
AssistantStreamEvent = ThreadCreated { data, event, enabled } | ThreadRunCreated { data, event } | ThreadRunQueued { data, event } | 21 moreRepresents an event emitted when streaming a Run.
Each event in a server-sent events stream has an event and data property:
event: thread.created
data: {"id": "thread_123", "object": "thread", ...}
We emit events whenever a new object is created, transitions to a new state, or is being
streamed in parts (deltas). For example, we emit thread.run.created when a new run
is created, thread.run.completed when a run completes, and so on. When an Assistant chooses
to create a message during a run, we emit a thread.message.created event, a
thread.message.in_progress event, many thread.message.delta events, and finally a
thread.message.completed event.
We may add additional events over time, so we recommend handling unknown events gracefully
in your code. See the Assistants API quickstart to learn how to
integrate the Assistants API with streaming.
Represents an event emitted when streaming a Run.
Each event in a server-sent events stream has an event and data property:
event: thread.created
data: {"id": "thread_123", "object": "thread", ...}We emit events whenever a new object is created, transitions to a new state, or is being
streamed in parts (deltas). For example, we emit thread.run.created when a new run
is created, thread.run.completed when a run completes, and so on. When an Assistant chooses
to create a message during a run, we emit a thread.message.created event, a
thread.message.in_progress event, many thread.message.delta events, and finally a
thread.message.completed event.
We may add additional events over time, so we recommend handling unknown events gracefully in your code. See the Assistants API quickstart to learn how to integrate the Assistants API with streaming.
ThreadCreated { data, event, enabled } Occurs when a new thread is created.
Occurs when a new thread is created.
ThreadRunCreated { data, event } Occurs when a new run is created.
Occurs when a new run is created.
ThreadRunQueued { data, event } Occurs when a run moves to a queued status.
Occurs when a run moves to a queued status.
ThreadRunInProgress { data, event } Occurs when a run moves to an in_progress status.
Occurs when a run moves to an in_progress status.
ThreadRunRequiresAction { data, event } Occurs when a run moves to a requires_action status.
Occurs when a run moves to a requires_action status.
ThreadRunCompleted { data, event } Occurs when a run is completed.
Occurs when a run is completed.
ThreadRunIncomplete { data, event } Occurs when a run ends with status incomplete.
Occurs when a run ends with status incomplete.
ThreadRunFailed { data, event } Occurs when a run fails.
Occurs when a run fails.
ThreadRunCancelling { data, event } Occurs when a run moves to a cancelling status.
Occurs when a run moves to a cancelling status.
ThreadRunCancelled { data, event } Occurs when a run is cancelled.
Occurs when a run is cancelled.
ThreadRunExpired { data, event } Occurs when a run expires.
Occurs when a run expires.
ThreadRunStepCreated { data, event } Occurs when a run step is created.
Occurs when a run step is created.
ThreadRunStepInProgress { data, event } Occurs when a run step moves to an in_progress state.
Occurs when a run step moves to an in_progress state.
ThreadRunStepDelta { data, event } Occurs when parts of a run step are being streamed.
Occurs when parts of a run step are being streamed.
ThreadRunStepCompleted { data, event } Occurs when a run step is completed.
Occurs when a run step is completed.
ThreadRunStepFailed { data, event } Occurs when a run step fails.
Occurs when a run step fails.
ThreadRunStepCancelled { data, event } Occurs when a run step is cancelled.
Occurs when a run step is cancelled.
ThreadRunStepExpired { data, event } Occurs when a run step expires.
Occurs when a run step expires.
ThreadMessageCreated { data, event } Occurs when a message is created.
Occurs when a message is created.
ThreadMessageInProgress { data, event } Occurs when a message moves to an in_progress state.
Occurs when a message moves to an in_progress state.
ThreadMessageDelta { data, event } Occurs when parts of a Message are being streamed.
Occurs when parts of a Message are being streamed.
ThreadMessageCompleted { data, event } Occurs when a message is completed.
Occurs when a message is completed.
ThreadMessageIncomplete { data, event } Occurs when a message ends before it is completed.
Occurs when a message ends before it is completed.
ErrorEvent { data, event } Occurs when an error occurs. This can happen due to an internal server error or a timeout.
Occurs when an error occurs. This can happen due to an internal server error or a timeout.
FileSearchTool { type, file_search }
file_search?: FileSearch { max_num_results, ranking_options } Overrides for the file search tool.
Overrides for the file search tool.
The maximum number of results the file search tool should output. The default is 20 for gpt-4* models and 5 for gpt-3.5-turbo. This number should be between 1 and 50 inclusive.
Note that the file search tool may output fewer than max_num_results results. See the file search tool documentation for more information.
ranking_options?: RankingOptions { score_threshold, ranker } The ranking options for the file search. If not specified, the file search tool will use the auto ranker and a score_threshold of 0.
See the file search tool documentation for more information.
The ranking options for the file search. If not specified, the file search tool will use the auto ranker and a score_threshold of 0.
See the file search tool documentation for more information.
MessageStreamEvent = ThreadMessageCreated { data, event } | ThreadMessageInProgress { data, event } | ThreadMessageDelta { data, event } | 2 moreOccurs when a message is created.
Occurs when a message is created.
ThreadMessageCreated { data, event } Occurs when a message is created.
Occurs when a message is created.
ThreadMessageInProgress { data, event } Occurs when a message moves to an in_progress state.
Occurs when a message moves to an in_progress state.
ThreadMessageDelta { data, event } Occurs when parts of a Message are being streamed.
Occurs when parts of a Message are being streamed.
ThreadMessageCompleted { data, event } Occurs when a message is completed.
Occurs when a message is completed.
RunStepStreamEvent = ThreadRunStepCreated { data, event } | ThreadRunStepInProgress { data, event } | ThreadRunStepDelta { data, event } | 4 moreOccurs when a run step is created.
Occurs when a run step is created.
ThreadRunStepCreated { data, event } Occurs when a run step is created.
Occurs when a run step is created.
ThreadRunStepInProgress { data, event } Occurs when a run step moves to an in_progress state.
Occurs when a run step moves to an in_progress state.
ThreadRunStepDelta { data, event } Occurs when parts of a run step are being streamed.
Occurs when parts of a run step are being streamed.
ThreadRunStepCompleted { data, event } Occurs when a run step is completed.
Occurs when a run step is completed.
ThreadRunStepFailed { data, event } Occurs when a run step fails.
Occurs when a run step fails.
ThreadRunStepCancelled { data, event } Occurs when a run step is cancelled.
Occurs when a run step is cancelled.
RunStreamEvent = ThreadRunCreated { data, event } | ThreadRunQueued { data, event } | ThreadRunInProgress { data, event } | 7 moreOccurs when a new run is created.
Occurs when a new run is created.
ThreadRunCreated { data, event } Occurs when a new run is created.
Occurs when a new run is created.
ThreadRunQueued { data, event } Occurs when a run moves to a queued status.
Occurs when a run moves to a queued status.
ThreadRunInProgress { data, event } Occurs when a run moves to an in_progress status.
Occurs when a run moves to an in_progress status.
ThreadRunRequiresAction { data, event } Occurs when a run moves to a requires_action status.
Occurs when a run moves to a requires_action status.
ThreadRunCompleted { data, event } Occurs when a run is completed.
Occurs when a run is completed.
ThreadRunIncomplete { data, event } Occurs when a run ends with status incomplete.
Occurs when a run ends with status incomplete.
ThreadRunFailed { data, event } Occurs when a run fails.
Occurs when a run fails.
ThreadRunCancelling { data, event } Occurs when a run moves to a cancelling status.
Occurs when a run moves to a cancelling status.
ThreadRunCancelled { data, event } Occurs when a run is cancelled.
Occurs when a run is cancelled.
BetaThreads
Build Assistants that can call models and use tools.
Create thread
Create thread and run
Retrieve thread
Modify thread
Delete thread
ModelsExpand Collapse
AssistantResponseFormatOption = "auto" | ResponseFormatText { type } | ResponseFormatJSONObject { type } | ResponseFormatJSONSchema { json_schema, type } Specifies the format that the model must output. Compatible with GPT-4o, GPT-4 Turbo, and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.
Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.
Setting to { "type": "json_object" } enables JSON mode, which ensures the message the model generates is valid JSON.
Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly “stuck” request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.
Specifies the format that the model must output. Compatible with GPT-4o, GPT-4 Turbo, and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.
Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.
Setting to { "type": "json_object" } enables JSON mode, which ensures the message the model generates is valid JSON.
Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly “stuck” request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.
ResponseFormatJSONObject { 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.
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.
ResponseFormatJSONSchema { json_schema, type } JSON Schema response format. Used to generate structured JSON responses.
Learn more about Structured Outputs.
JSON Schema response format. Used to generate structured JSON responses. Learn more about Structured Outputs.
json_schema: JSONSchema { name, description, schema, strict } Structured Outputs configuration options, including a JSON Schema.
Structured Outputs configuration options, including a JSON Schema.
The name of the response format. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
A description of what the response format is for, used by the model to determine how to respond in the format.
The schema for the response format, described as a JSON Schema object. Learn how to build JSON schemas here.
Whether to enable strict schema adherence when generating the output.
If set to true, the model will always follow the exact schema defined
in the schema field. Only a subset of JSON Schema is supported when
strict is true. To learn more, read the Structured Outputs
guide.
Controls which (if any) tool is called by the model.
none means the model will not call any tools and instead generates a message.
auto is the default value and means the model can pick between generating a message or calling one or more tools.
required means the model must call one or more tools before responding to the user.
Specifying a particular tool like {"type": "file_search"} or {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.
Controls which (if any) tool is called by the model.
none means the model will not call any tools and instead generates a message.
auto is the default value and means the model can pick between generating a message or calling one or more tools.
required means the model must call one or more tools before responding to the user.
Specifying a particular tool like {"type": "file_search"} or {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.
Thread { id, created_at, metadata, 2 more } Represents a thread that contains messages.
Represents a thread that contains messages.
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
tool_resources: ToolResources | nullA set of resources that are made available to the assistant’s tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.
A set of resources that are made available to the assistant’s tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.
code_interpreter?: CodeInterpreter { file_ids }
A list of file IDs made available to the code_interpreter tool. There can be a maximum of 20 files associated with the tool.
file_search?: FileSearch { vector_store_ids }
The vector store attached to this thread. There can be a maximum of 1 vector store attached to the thread.
BetaThreadsRuns
Build Assistants that can call models and use tools.
Create run
Retrieve run
Modify run
Submit tool outputs to run
Cancel a run
ModelsExpand Collapse
RequiredActionFunctionToolCall { id, function, type } Tool call objects
Tool call objects
The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the Submit tool outputs to run endpoint.
Run { id, assistant_id, cancelled_at, 24 more } Represents an execution run on a thread.
Represents an execution run on a thread.
The ID of the assistant used for execution of this run.
The Unix timestamp (in seconds) for when the run was cancelled.
The Unix timestamp (in seconds) for when the run was completed.
The Unix timestamp (in seconds) for when the run will expire.
incomplete_details: IncompleteDetails | nullDetails on why the run is incomplete. Will be null if the run is not incomplete.
Details on why the run is incomplete. Will be null if the run is not incomplete.
The instructions that the assistant used for this run.
last_error: LastError | nullThe last error associated with this run. Will be null if there are no errors.
The last error associated with this run. Will be null if there are no errors.
The maximum number of completion tokens specified to have been used over the course of the run.
The maximum number of prompt tokens specified to have been used over the course of the run.
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
The model that the assistant used for this run.
Whether to enable parallel function calling during tool use.
required_action: RequiredAction | nullDetails on the action required to continue the run. Will be null if no action is required.
Details on the action required to continue the run. Will be null if no action is required.
submit_tool_outputs: SubmitToolOutputs { tool_calls } Details on the tool outputs needed for this run to continue.
Details on the tool outputs needed for this run to continue.
A list of the relevant tool calls.
A list of the relevant tool calls.
The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the Submit tool outputs to run endpoint.
Specifies the format that the model must output. Compatible with GPT-4o, GPT-4 Turbo, and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.
Setting to { "type": "json_schema", "json_schema": {...} } enables Structured Outputs which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.
Setting to { "type": "json_object" } enables JSON mode, which ensures the message the model generates is valid JSON.
Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly “stuck” request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.
The Unix timestamp (in seconds) for when the run was started.
The ID of the thread that was executed on as a part of this run.
Controls which (if any) tool is called by the model.
none means the model will not call any tools and instead generates a message.
auto is the default value and means the model can pick between generating a message or calling one or more tools.
required means the model must call one or more tools before responding to the user.
Specifying a particular tool like {"type": "file_search"} or {"type": "function", "function": {"name": "my_function"}} forces the model to call that tool.
The list of tools that the assistant used for this run.
truncation_strategy: TruncationStrategy | nullControls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run.
Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run.
type: "auto" | "last_messages"The truncation strategy to use for the thread. The default is auto. If set to last_messages, the thread will be truncated to the n most recent messages in the thread. When set to auto, messages in the middle of the thread will be dropped to fit the context length of the model, max_prompt_tokens.
The truncation strategy to use for the thread. The default is auto. If set to last_messages, the thread will be truncated to the n most recent messages in the thread. When set to auto, messages in the middle of the thread will be dropped to fit the context length of the model, max_prompt_tokens.
BetaThreadsRunsSteps
Build Assistants that can call models and use tools.
List run steps
Retrieve run step
ModelsExpand Collapse
CodeInterpreterOutputImage { index, type, image }
image?: Image { file_id }
The file ID of the image.
CodeInterpreterToolCall { id, code_interpreter, type } Details of the Code Interpreter tool call the run step was involved in.
Details of the Code Interpreter tool call the run step was involved in.
code_interpreter: CodeInterpreter { input, outputs } The Code Interpreter tool call definition.
The Code Interpreter tool call definition.
outputs: Array<Logs { logs, type } | Image { image, type } >The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (logs) or images (image). Each of these are represented by a different object type.
The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (logs) or images (image). Each of these are represented by a different object type.
Image { image, type }
image: Image { file_id }
The file ID of the image.
CodeInterpreterToolCallDelta { index, type, id, code_interpreter } Details of the Code Interpreter tool call the run step was involved in.
Details of the Code Interpreter tool call the run step was involved in.
The type of tool call. This is always going to be code_interpreter for this type of tool call.
code_interpreter?: CodeInterpreter { input, outputs } The Code Interpreter tool call definition.
The Code Interpreter tool call definition.
outputs?: Array<CodeInterpreterLogs { index, type, logs } | CodeInterpreterOutputImage { index, type, image } >The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (logs) or images (image). Each of these are represented by a different object type.
The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (logs) or images (image). Each of these are represented by a different object type.
CodeInterpreterLogs { index, type, logs } Text output from the Code Interpreter tool call as part of a run step.
Text output from the Code Interpreter tool call as part of a run step.
CodeInterpreterOutputImage { index, type, image }
image?: Image { file_id }
The file ID of the image.
FileSearchToolCall { id, file_search, type }
file_search: FileSearch { ranking_options, results } For now, this is always going to be an empty object.
For now, this is always going to be an empty object.
ranking_options?: RankingOptions { ranker, score_threshold } The ranking options for the file search.
The ranking options for the file search.
FunctionToolCall { id, function, type }
function: Function { arguments, name, output } The definition of the function that was called.
The definition of the function that was called.
The output of the function. This will be null if the outputs have not been submitted yet.
FunctionToolCallDelta { index, type, id, function }
The type of tool call. This is always going to be function for this type of tool call.
function?: Function { arguments, name, output } The definition of the function that was called.
The definition of the function that was called.
The output of the function. This will be null if the outputs have not been submitted yet.
RunStep { id, assistant_id, cancelled_at, 13 more } Represents a step in execution of a run.
Represents a step in execution of a run.
The ID of the assistant associated with the run step.
The Unix timestamp (in seconds) for when the run step was cancelled.
The Unix timestamp (in seconds) for when the run step completed.
The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired.
last_error: LastError | nullThe last error associated with this run step. Will be null if there are no errors.
The last error associated with this run step. Will be null if there are no errors.
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
The ID of the run that this run step is a part of.
status: "in_progress" | "cancelled" | "failed" | 2 moreThe status of the run step, which can be either in_progress, cancelled, failed, completed, or expired.
The status of the run step, which can be either in_progress, cancelled, failed, completed, or expired.
step_details: MessageCreationStepDetails { message_creation, type } | ToolCallsStepDetails { tool_calls, type } The details of the run step.
The details of the run step.
The ID of the thread that was run.
type: "message_creation" | "tool_calls"The type of run step, which can be either message_creation or tool_calls.
The type of run step, which can be either message_creation or tool_calls.
BetaThreadsMessages
Build Assistants that can call models and use tools.
List messages
Create message
Modify message
Retrieve message
Delete message
ModelsExpand Collapse
FileCitationDeltaAnnotation { index, type, end_index, 3 more } A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the “file_search” tool to search files.
A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the “file_search” tool to search files.
ImageFile { file_id, detail }
The File ID of the image in the message content. Set purpose="vision" when uploading the File if you need to later display the file content.
ImageFileDelta { detail, file_id }
detail?: "auto" | "low" | "high"Specifies the detail level of the image if specified by the user. low uses fewer tokens, you can opt in to high resolution using high.
Specifies the detail level of the image if specified by the user. low uses fewer tokens, you can opt in to high resolution using high.
The File ID of the image in the message content. Set purpose="vision" when uploading the File if you need to later display the file content.
ImageFileDeltaBlock { index, type, image_file } References an image File in the content of a message.
References an image File in the content of a message.
Message { id, assistant_id, attachments, 11 more } Represents a message within a thread.
Represents a message within a thread.
If applicable, the ID of the assistant that authored this message.
attachments: Array<Attachment> | nullA list of files attached to the message, and the tools they were added to.
A list of files attached to the message, and the tools they were added to.
The Unix timestamp (in seconds) for when the message was completed.
The Unix timestamp (in seconds) for when the message was marked as incomplete.
incomplete_details: IncompleteDetails | nullOn an incomplete message, details about why the message is incomplete.
On an incomplete message, details about why the message is incomplete.
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.
Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.
The ID of the run associated with the creation of this message. Value is null when messages are created manually using the create message or create thread endpoints.
status: "in_progress" | "incomplete" | "completed"The status of the message, which can be either in_progress, incomplete, or completed.
The status of the message, which can be either in_progress, incomplete, or completed.
The thread ID that this message belongs to.
MessageContentPartParam = ImageFileContentBlock { image_file, type } | ImageURLContentBlock { image_url, type } | TextContentBlockParam { text, type } References an image File in the content of a message.
References an image File in the content of a message.
ImageFileContentBlock { image_file, type } References an image File in the content of a message.
References an image File in the content of a message.
BetaResponses
Create a model response
Get a model response
Delete a model response
Cancel a response
Compact a response
ModelsExpand Collapse
BetaCompactedResponse { id, created_at, object, 2 more }
Unix timestamp (in seconds) when the compacted conversation was created.
The compacted list of output items. This is a list of all user messages, followed by a single compaction item.
The compacted list of output items. This is a list of all user messages, followed by a single compaction item.
BetaResponseOutputMessage { id, content, role, 4 more } An output message from the model.
An output message from the model.
content: Array<BetaResponseOutputText { annotations, text, type, logprobs } | BetaResponseOutputRefusal { refusal, type } >The content of the output message.
The content of the output message.
BetaResponseOutputText { annotations, text, type, logprobs } A text output from the model.
A text output from the model.
annotations: Array<FileCitation { file_id, filename, index, type } | URLCitation { end_index, start_index, title, 2 more } | ContainerFileCitation { container_id, end_index, file_id, 3 more } | FilePath { file_id, index, type } >The annotations of the text output.
The annotations of the text output.
URLCitation { end_index, start_index, title, 2 more } A citation for a web resource used to generate a model response.
A citation for a web resource used to generate a model response.
status: "in_progress" | "completed" | "incomplete"The status of the message input. One of in_progress, completed, or
incomplete. Populated when input items are returned via API.
The status of the message input. One of in_progress, completed, or
incomplete. Populated when input items are returned via API.
Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer).
For models like gpt-5.3-codex and beyond, when sending follow-up requests, preserve and resend
phase on all assistant messages — dropping it can degrade performance. Not used for user messages.
BetaResponseFileSearchToolCall { id, queries, status, 3 more } The results of a file search tool call. See the
file search guide for more information.
The results of a file search tool call. See the file search guide for more information.
status: "in_progress" | "searching" | "completed" | 2 moreThe status of the file search tool call. One of in_progress,
searching, incomplete or failed,
The status of the file search tool call. One of in_progress,
searching, incomplete or failed,
results?: Array<Result> | nullThe results of the file search tool call.
The results of the file search tool call.
attributes?: Record<string, string | number | boolean> | nullSet of 16 key-value pairs that can be attached to an object. This can be
useful for storing additional information about the object in a structured
format, and querying for objects via API or the dashboard. Keys are strings
with a maximum length of 64 characters. Values are strings with a maximum
length of 512 characters, booleans, or numbers.
Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters, booleans, or numbers.
BetaResponseFunctionToolCall { arguments, call_id, name, 6 more } A tool call to run a function. See the
function calling guide for more information.
A tool call to run a function. See the function calling guide for more information.
BetaResponseFunctionToolCallOutputItem { id, call_id, output, 5 more }
output: string | Array<BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseInputImage { detail, type, file_id, 2 more } | BetaResponseInputFile { type, detail, file_data, 4 more } >The output from the function call generated by your code.
Can be a string or an list of output content.
The output from the function call generated by your code. Can be a string or an list of output content.
Array<BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseInputImage { detail, type, file_id, 2 more } | BetaResponseInputFile { type, detail, file_data, 4 more } >
BetaResponseInputImage { detail, type, file_id, 2 more } An image input to the model. Learn about image inputs.
An image input to the model. Learn about image inputs.
BetaResponseInputFile { type, detail, file_data, 4 more } A file input to the model.
A file input to the model.
detail?: "auto" | "low" | "high"The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.
The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.
status: "in_progress" | "completed" | "incomplete"The status of the item. One of in_progress, completed, or
incomplete. Populated when items are returned via API.
The status of the item. One of in_progress, completed, or
incomplete. Populated when items are returned via API.
AgentMessage { id, author, content, 3 more }
content: Array<BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseOutputText { annotations, text, type, logprobs } | Text { text, type } | 7 more>Encrypted content sent between agents.
Encrypted content sent between agents.
BetaResponseOutputText { annotations, text, type, logprobs } A text output from the model.
A text output from the model.
annotations: Array<FileCitation { file_id, filename, index, type } | URLCitation { end_index, start_index, title, 2 more } | ContainerFileCitation { container_id, end_index, file_id, 3 more } | FilePath { file_id, index, type } >The annotations of the text output.
The annotations of the text output.
URLCitation { end_index, start_index, title, 2 more } A citation for a web resource used to generate a model response.
A citation for a web resource used to generate a model response.
BetaResponseInputImage { detail, type, file_id, 2 more } An image input to the model. Learn about image inputs.
An image input to the model. Learn about image inputs.
ComputerScreenshot { detail, file_id, image_url, 2 more } A screenshot of a computer.
A screenshot of a computer.
BetaResponseInputFile { type, detail, file_data, 4 more } A file input to the model.
A file input to the model.
detail?: "auto" | "low" | "high"The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.
The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.
MultiAgentCall { id, action, arguments, 3 more }
MultiAgentCallOutput { id, action, call_id, 3 more }
action: "spawn_agent" | "interrupt_agent" | "list_agents" | 3 moreThe multi-agent action that produced this result.
The multi-agent action that produced this result.
Text output returned by the multi-agent action.
Text output returned by the multi-agent action.
annotations: Array<FileCitation { file_id, filename, index, type } | URLCitation { end_index, start_index, title, 2 more } | ContainerFileCitation { container_id, end_index, file_id, 3 more } | FilePath { file_id, index, type } >The annotations of the text output.
The annotations of the text output.
URLCitation { end_index, start_index, title, 2 more } A citation for a web resource used to generate a model response.
A citation for a web resource used to generate a model response.
BetaResponseFunctionWebSearch { id, action, status, 2 more } The results of a web search tool call. See the
web search guide for more information.
The results of a web search tool call. See the web search guide for more information.
action: Search { type, queries, query, sources } | OpenPage { type, url } | FindInPage { pattern, type, url } An object describing the specific action taken in this web search call.
Includes details on how the model used the web (search, open_page, find_in_page).
An object describing the specific action taken in this web search call. Includes details on how the model used the web (search, open_page, find_in_page).
BetaResponseComputerToolCall { id, call_id, pending_safety_checks, 5 more } A tool call to a computer use tool. See the
computer use guide for more information.
A tool call to a computer use tool. See the computer use guide for more information.
status: "in_progress" | "completed" | "incomplete"The status of the item. One of in_progress, completed, or
incomplete. Populated when items are returned via API.
The status of the item. One of in_progress, completed, or
incomplete. Populated when items are returned via API.
BetaResponseComputerToolCallOutputItem { id, call_id, output, 5 more }
status: "completed" | "incomplete" | "failed" | "in_progress"The status of the message input. One of in_progress, completed, or
incomplete. Populated when input items are returned via API.
The status of the message input. One of in_progress, completed, or
incomplete. Populated when input items are returned via API.
acknowledged_safety_checks?: Array<AcknowledgedSafetyCheck>The safety checks reported by the API that have been acknowledged by the
developer.
The safety checks reported by the API that have been acknowledged by the developer.
BetaResponseReasoningItem { id, summary, type, 4 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.
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.
ProgramOutput { id, call_id, result, 3 more }
BetaResponseToolSearchCall { id, arguments, call_id, 5 more }
BetaResponseToolSearchOutputItem { id, call_id, execution, 5 more }
status: "in_progress" | "completed" | "incomplete"The status of the tool search output item that was recorded.
The status of the tool search output item that was recorded.
The loaded tool definitions returned by tool search.
The loaded tool definitions returned by tool search.
BetaFunctionTool { name, parameters, strict, 5 more } Defines a function in your own code the model can choose to call. Learn more about function calling.
Defines a function in your own code the model can choose to call. Learn more about function calling.
A JSON schema object describing the parameters of the function.
BetaFileSearchTool { type, vector_store_ids, filters, 2 more } A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type } | nullA filter to apply.
A filter to apply.
ComparisonFilter { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
CompoundFilter { filters, type } Combine multiple filters using and or or.
Combine multiple filters using and or or.
filters: Array<ComparisonFilter { key, type, value } | unknown>Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
ComparisonFilter { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold } Ranking options for search.
Ranking options for search.
BetaComputerTool { type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
BetaComputerUsePreviewTool { display_height, display_width, environment, type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
BetaWebSearchTool { type, filters, search_context_size, user_location } Search the Internet for sources related to the prompt. Learn more about the
web search tool.
Search the Internet for sources related to the prompt. Learn more about the web search tool.
type: "web_search" | "web_search_2025_08_26"The type of the web search tool. One of web_search or web_search_2025_08_26.
The type of the web search tool. One of web_search or web_search_2025_08_26.
search_context_size?: "low" | "medium" | "high"High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
user_location?: UserLocation | nullThe approximate location of the user.
The approximate location of the user.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
Mcp { server_label, type, allowed_callers, 9 more } Give the model access to additional tools via remote Model Context Protocol
(MCP) servers. Learn more about MCP.
Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.
allowed_tools?: Array<string> | McpToolFilter { read_only, tool_names } | nullList of allowed tool names or a filter object.
List of allowed tool names or a filter object.
McpToolFilter { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here.
connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 moreIdentifier for service connectors, like those available in ChatGPT. One of
server_url, connector_id, or tunnel_id must be provided. Learn more
about service connectors here.
Currently supported connector_id values are:
- Dropbox:
connector_dropbox
- Gmail:
connector_gmail
- Google Calendar:
connector_googlecalendar
- Google Drive:
connector_googledrive
- Microsoft Teams:
connector_microsoftteams
- Outlook Calendar:
connector_outlookcalendar
- Outlook Email:
connector_outlookemail
- SharePoint:
connector_sharepoint
Identifier for service connectors, like those available in ChatGPT. One of
server_url, connector_id, or tunnel_id must be provided. Learn more
about service connectors here.
Currently supported connector_id values are:
- Dropbox:
connector_dropbox - Gmail:
connector_gmail - Google Calendar:
connector_googlecalendar - Google Drive:
connector_googledrive - Microsoft Teams:
connector_microsoftteams - Outlook Calendar:
connector_outlookcalendar - Outlook Email:
connector_outlookemail - SharePoint:
connector_sharepoint
Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.
require_approval?: McpToolApprovalFilter { always, never } | "always" | "never" | nullSpecify which of the MCP server’s tools require approval.
Specify which of the MCP server’s tools require approval.
McpToolApprovalFilter { always, never } Specify which of the MCP server’s tools require approval. Can be
always, never, or a filter object associated with tools
that require approval.
Specify which of the MCP server’s tools require approval. Can be
always, never, or a filter object associated with tools
that require approval.
always?: Always { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
never?: Never { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
CodeInterpreter { container, type, allowed_callers } A tool that runs Python code to help generate a response to a prompt.
A tool that runs Python code to help generate a response to a prompt.
container: string | CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy } The code interpreter container. Can be a container ID or an object that
specifies uploaded file IDs to make available to your code, along with an
optional memory_limit setting.
The code interpreter container. Can be a container ID or an object that
specifies uploaded file IDs to make available to your code, along with an
optional memory_limit setting.
CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy } Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
memory_limit?: "1g" | "4g" | "16g" | "64g" | nullThe memory limit for the code interpreter container.
The memory limit for the code interpreter container.
network_policy?: BetaContainerNetworkPolicyDisabled { type } | BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
ImageGeneration { type, action, background, 9 more } A tool that generates images using the GPT image models.
A tool that generates images using the GPT image models.
action?: "generate" | "edit" | "auto"Whether to generate a new image or edit an existing image. Default: auto.
Whether to generate a new image or edit an existing image. Default: auto.
background?: "transparent" | "opaque" | "auto"Allows to set transparency for the background of the generated image(s).
This parameter is only supported for GPT image models that support
transparent backgrounds. Must be one of transparent, opaque, or
auto (default value). When auto is used, the model will
automatically determine the best background for the image.
gpt-image-2 and gpt-image-2-2026-04-21 do not support
transparent backgrounds. Requests with background set to
transparent will return an error for these models; use opaque or
auto instead.
If transparent, the output format needs to support transparency,
so it should be set to either png (default value) or webp.
Allows to set transparency for the background of the generated image(s).
This parameter is only supported for GPT image models that support
transparent backgrounds. Must be one of transparent, opaque, or
auto (default value). When auto is used, the model will
automatically determine the best background for the image.
gpt-image-2 and gpt-image-2-2026-04-21 do not support
transparent backgrounds. Requests with background set to
transparent will return an error for these models; use opaque or
auto instead.
If transparent, the output format needs to support transparency,
so it should be set to either png (default value) or webp.
input_fidelity?: "high" | "low" | nullControl how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini. Supports high and low. Defaults to low.
Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini. Supports high and low. Defaults to low.
input_image_mask?: InputImageMask { file_id, image_url } Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-2" | 3 moreThe image generation model to use. Default: gpt-image-1.
The image generation model to use. Default: gpt-image-1.
output_format?: "png" | "webp" | "jpeg"The output format of the generated image. One of png, webp, or
jpeg. Default: png.
The output format of the generated image. One of png, webp, or
jpeg. Default: png.
Number of partial images to generate in streaming mode, from 0 (default value) to 3.
quality?: "low" | "medium" | "high" | "auto"The quality of the generated image. One of low, medium, high,
or auto. Default: auto.
The quality of the generated image. One of low, medium, high,
or auto. Default: auto.
size?: (string & {}) | "1024x1024" | "1024x1536" | "1536x1024" | "auto"The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model’s current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model’s current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
BetaFunctionShellTool { type, allowed_callers, environment } A tool that allows the model to execute shell commands.
A tool that allows the model to execute shell commands.
environment?: BetaContainerAuto { type, file_ids, memory_limit, 2 more } | BetaLocalEnvironment { type, skills } | BetaContainerReference { container_id, type } | null
BetaContainerAuto { type, file_ids, memory_limit, 2 more }
network_policy?: BetaContainerNetworkPolicyDisabled { type } | BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
skills?: Array<BetaSkillReference { skill_id, type, version } | BetaInlineSkill { description, name, source, type } >An optional list of skills referenced by id or inline data.
An optional list of skills referenced by id or inline data.
BetaCustomTool { name, type, allowed_callers, 3 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
BetaNamespaceTool { description, name, tools, type } Groups function/custom tools under a shared namespace.
Groups function/custom tools under a shared namespace.
tools: Array<Function { name, type, allowed_callers, 5 more } | BetaCustomTool { name, type, allowed_callers, 3 more } >The function/custom tools available inside this namespace.
The function/custom tools available inside this namespace.
Function { name, type, allowed_callers, 5 more }
BetaCustomTool { name, type, allowed_callers, 3 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
BetaToolSearchTool { type, description, execution, parameters } Hosted or BYOT tool search configuration for deferred tools.
Hosted or BYOT tool search configuration for deferred tools.
BetaWebSearchPreviewTool { type, search_content_types, search_context_size, user_location } This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
type: "web_search_preview" | "web_search_preview_2025_03_11"The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.
The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.
search_context_size?: "low" | "medium" | "high"High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
user_location?: UserLocation | nullThe user’s location.
The user’s location.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
AdditionalTools { id, role, tools, 2 more }
The additional tool definitions made available at this item.
The additional tool definitions made available at this item.
BetaFunctionTool { name, parameters, strict, 5 more } Defines a function in your own code the model can choose to call. Learn more about function calling.
Defines a function in your own code the model can choose to call. Learn more about function calling.
A JSON schema object describing the parameters of the function.
BetaFileSearchTool { type, vector_store_ids, filters, 2 more } A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type } | nullA filter to apply.
A filter to apply.
ComparisonFilter { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
CompoundFilter { filters, type } Combine multiple filters using and or or.
Combine multiple filters using and or or.
filters: Array<ComparisonFilter { key, type, value } | unknown>Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
ComparisonFilter { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold } Ranking options for search.
Ranking options for search.
BetaComputerTool { type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
BetaComputerUsePreviewTool { display_height, display_width, environment, type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
BetaWebSearchTool { type, filters, search_context_size, user_location } Search the Internet for sources related to the prompt. Learn more about the
web search tool.
Search the Internet for sources related to the prompt. Learn more about the web search tool.
type: "web_search" | "web_search_2025_08_26"The type of the web search tool. One of web_search or web_search_2025_08_26.
The type of the web search tool. One of web_search or web_search_2025_08_26.
search_context_size?: "low" | "medium" | "high"High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
user_location?: UserLocation | nullThe approximate location of the user.
The approximate location of the user.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
Mcp { server_label, type, allowed_callers, 9 more } Give the model access to additional tools via remote Model Context Protocol
(MCP) servers. Learn more about MCP.
Give the model access to additional tools via remote Model Context Protocol (MCP) servers. Learn more about MCP.
allowed_tools?: Array<string> | McpToolFilter { read_only, tool_names } | nullList of allowed tool names or a filter object.
List of allowed tool names or a filter object.
McpToolFilter { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
An OAuth access token that can be used with a remote MCP server, either with a custom MCP server URL or a service connector. Your application must handle the OAuth authorization flow and provide the token here.
connector_id?: "connector_dropbox" | "connector_gmail" | "connector_googlecalendar" | 5 moreIdentifier for service connectors, like those available in ChatGPT. One of
server_url, connector_id, or tunnel_id must be provided. Learn more
about service connectors here.
Currently supported connector_id values are:
- Dropbox:
connector_dropbox
- Gmail:
connector_gmail
- Google Calendar:
connector_googlecalendar
- Google Drive:
connector_googledrive
- Microsoft Teams:
connector_microsoftteams
- Outlook Calendar:
connector_outlookcalendar
- Outlook Email:
connector_outlookemail
- SharePoint:
connector_sharepoint
Identifier for service connectors, like those available in ChatGPT. One of
server_url, connector_id, or tunnel_id must be provided. Learn more
about service connectors here.
Currently supported connector_id values are:
- Dropbox:
connector_dropbox - Gmail:
connector_gmail - Google Calendar:
connector_googlecalendar - Google Drive:
connector_googledrive - Microsoft Teams:
connector_microsoftteams - Outlook Calendar:
connector_outlookcalendar - Outlook Email:
connector_outlookemail - SharePoint:
connector_sharepoint
Optional HTTP headers to send to the MCP server. Use for authentication or other purposes.
require_approval?: McpToolApprovalFilter { always, never } | "always" | "never" | nullSpecify which of the MCP server’s tools require approval.
Specify which of the MCP server’s tools require approval.
McpToolApprovalFilter { always, never } Specify which of the MCP server’s tools require approval. Can be
always, never, or a filter object associated with tools
that require approval.
Specify which of the MCP server’s tools require approval. Can be
always, never, or a filter object associated with tools
that require approval.
always?: Always { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
never?: Never { read_only, tool_names } A filter object to specify which tools are allowed.
A filter object to specify which tools are allowed.
Indicates whether or not a tool modifies data or is read-only. If an
MCP server is annotated with readOnlyHint,
it will match this filter.
CodeInterpreter { container, type, allowed_callers } A tool that runs Python code to help generate a response to a prompt.
A tool that runs Python code to help generate a response to a prompt.
container: string | CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy } The code interpreter container. Can be a container ID or an object that
specifies uploaded file IDs to make available to your code, along with an
optional memory_limit setting.
The code interpreter container. Can be a container ID or an object that
specifies uploaded file IDs to make available to your code, along with an
optional memory_limit setting.
CodeInterpreterToolAuto { type, file_ids, memory_limit, network_policy } Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
memory_limit?: "1g" | "4g" | "16g" | "64g" | nullThe memory limit for the code interpreter container.
The memory limit for the code interpreter container.
network_policy?: BetaContainerNetworkPolicyDisabled { type } | BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
ImageGeneration { type, action, background, 9 more } A tool that generates images using the GPT image models.
A tool that generates images using the GPT image models.
action?: "generate" | "edit" | "auto"Whether to generate a new image or edit an existing image. Default: auto.
Whether to generate a new image or edit an existing image. Default: auto.
background?: "transparent" | "opaque" | "auto"Allows to set transparency for the background of the generated image(s).
This parameter is only supported for GPT image models that support
transparent backgrounds. Must be one of transparent, opaque, or
auto (default value). When auto is used, the model will
automatically determine the best background for the image.
gpt-image-2 and gpt-image-2-2026-04-21 do not support
transparent backgrounds. Requests with background set to
transparent will return an error for these models; use opaque or
auto instead.
If transparent, the output format needs to support transparency,
so it should be set to either png (default value) or webp.
Allows to set transparency for the background of the generated image(s).
This parameter is only supported for GPT image models that support
transparent backgrounds. Must be one of transparent, opaque, or
auto (default value). When auto is used, the model will
automatically determine the best background for the image.
gpt-image-2 and gpt-image-2-2026-04-21 do not support
transparent backgrounds. Requests with background set to
transparent will return an error for these models; use opaque or
auto instead.
If transparent, the output format needs to support transparency,
so it should be set to either png (default value) or webp.
input_fidelity?: "high" | "low" | nullControl how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini. Supports high and low. Defaults to low.
Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for gpt-image-1 and gpt-image-1.5 and later models, unsupported for gpt-image-1-mini. Supports high and low. Defaults to low.
input_image_mask?: InputImageMask { file_id, image_url } Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
Optional mask for inpainting. Contains image_url
(string, optional) and file_id (string, optional).
model?: (string & {}) | "gpt-image-1" | "gpt-image-1-mini" | "gpt-image-2" | 3 moreThe image generation model to use. Default: gpt-image-1.
The image generation model to use. Default: gpt-image-1.
output_format?: "png" | "webp" | "jpeg"The output format of the generated image. One of png, webp, or
jpeg. Default: png.
The output format of the generated image. One of png, webp, or
jpeg. Default: png.
Number of partial images to generate in streaming mode, from 0 (default value) to 3.
quality?: "low" | "medium" | "high" | "auto"The quality of the generated image. One of low, medium, high,
or auto. Default: auto.
The quality of the generated image. One of low, medium, high,
or auto. Default: auto.
size?: (string & {}) | "1024x1024" | "1024x1536" | "1536x1024" | "auto"The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model’s current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
The size of the generated images. For gpt-image-2 and gpt-image-2-2026-04-21, arbitrary resolutions are supported as WIDTHxHEIGHT strings, for example 1536x864. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above 2560x1440 are experimental, and the maximum supported resolution is 3840x2160. The requested size must also satisfy the model’s current pixel and edge limits. The standard sizes 1024x1024, 1536x1024, and 1024x1536 are supported by the GPT image models; auto is supported for models that allow automatic sizing. For dall-e-2, use one of 256x256, 512x512, or 1024x1024. For dall-e-3, use one of 1024x1024, 1792x1024, or 1024x1792.
BetaFunctionShellTool { type, allowed_callers, environment } A tool that allows the model to execute shell commands.
A tool that allows the model to execute shell commands.
environment?: BetaContainerAuto { type, file_ids, memory_limit, 2 more } | BetaLocalEnvironment { type, skills } | BetaContainerReference { container_id, type } | null
BetaContainerAuto { type, file_ids, memory_limit, 2 more }
network_policy?: BetaContainerNetworkPolicyDisabled { type } | BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
skills?: Array<BetaSkillReference { skill_id, type, version } | BetaInlineSkill { description, name, source, type } >An optional list of skills referenced by id or inline data.
An optional list of skills referenced by id or inline data.
BetaCustomTool { name, type, allowed_callers, 3 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
BetaNamespaceTool { description, name, tools, type } Groups function/custom tools under a shared namespace.
Groups function/custom tools under a shared namespace.
tools: Array<Function { name, type, allowed_callers, 5 more } | BetaCustomTool { name, type, allowed_callers, 3 more } >The function/custom tools available inside this namespace.
The function/custom tools available inside this namespace.
Function { name, type, allowed_callers, 5 more }
BetaCustomTool { name, type, allowed_callers, 3 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
BetaToolSearchTool { type, description, execution, parameters } Hosted or BYOT tool search configuration for deferred tools.
Hosted or BYOT tool search configuration for deferred tools.
BetaWebSearchPreviewTool { type, search_content_types, search_context_size, user_location } This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
This tool searches the web for relevant results to use in a response. Learn more about the web search tool.
type: "web_search_preview" | "web_search_preview_2025_03_11"The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.
The type of the web search tool. One of web_search_preview or web_search_preview_2025_03_11.
search_context_size?: "low" | "medium" | "high"High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
High level guidance for the amount of context window space to use for the search. One of low, medium, or high. medium is the default.
user_location?: UserLocation | nullThe user’s location.
The user’s location.
The two-letter ISO country code of the user, e.g. US.
The IANA timezone of the user, e.g. America/Los_Angeles.
BetaResponseCompactionItem { id, encrypted_content, type, 2 more } A compaction item generated by the v1/responses/compact API.
A compaction item generated by the v1/responses/compact API.
ImageGenerationCall { id, result, status, 2 more } An image generation request made by the model.
An image generation request made by the model.
BetaResponseCodeInterpreterToolCall { id, code, container_id, 4 more } A tool call to run code.
A tool call to run code.
outputs: Array<Logs { logs, type } | Image { type, url } > | nullThe outputs generated by the code interpreter, such as logs or images.
Can be null if no outputs are available.
The outputs generated by the code interpreter, such as logs or images. Can be null if no outputs are available.
status: "in_progress" | "completed" | "incomplete" | 2 moreThe status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.
The status of the code interpreter tool call. Valid values are in_progress, completed, incomplete, interpreting, and failed.
LocalShellCall { id, action, call_id, 3 more } A tool call to run a command on the local shell.
A tool call to run a command on the local shell.
LocalShellCallOutput { id, output, type, 2 more } The output of a local shell tool call.
The output of a local shell tool call.
BetaResponseFunctionShellToolCall { id, action, call_id, 6 more } A tool call that executes one or more shell commands in a managed environment.
A tool call that executes one or more shell commands in a managed environment.
action: Action { commands, max_output_length, timeout_ms } The shell commands and limits that describe how to run the tool call.
The shell commands and limits that describe how to run the tool call.
environment: BetaResponseLocalEnvironment { type } | BetaResponseContainerReference { container_id, type } | nullRepresents the use of a local environment to perform shell actions.
Represents the use of a local environment to perform shell actions.
status: "in_progress" | "completed" | "incomplete"The status of the shell call. One of in_progress, completed, or incomplete.
The status of the shell call. One of in_progress, completed, or incomplete.
BetaResponseFunctionShellToolCallOutput { id, call_id, max_output_length, 6 more } The output of a shell tool call that was emitted.
The output of a shell tool call that was emitted.
The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output.
output: Array<Output>An array of shell call output contents
An array of shell call output contents
status: "in_progress" | "completed" | "incomplete"The status of the shell call output. One of in_progress, completed, or incomplete.
The status of the shell call output. One of in_progress, completed, or incomplete.
BetaResponseApplyPatchToolCall { id, call_id, operation, 5 more } A tool call that applies file diffs by creating, deleting, or updating files.
A tool call that applies file diffs by creating, deleting, or updating files.
operation: CreateFile { diff, path, type } | DeleteFile { path, type } | UpdateFile { diff, path, type } One of the create_file, delete_file, or update_file operations applied via apply_patch.
One of the create_file, delete_file, or update_file operations applied via apply_patch.
status: "in_progress" | "completed"The status of the apply patch tool call. One of in_progress or completed.
The status of the apply patch tool call. One of in_progress or completed.
BetaResponseApplyPatchToolCallOutput { id, call_id, status, 5 more } The output emitted by an apply patch tool call.
The output emitted by an apply patch tool call.
The unique ID of the apply patch tool call output. Populated when this item is returned via API.
status: "completed" | "failed"The status of the apply patch tool call output. One of completed or failed.
The status of the apply patch tool call output. One of completed or failed.
McpCall { id, arguments, name, 7 more } An invocation of a tool on an MCP server.
An invocation of a tool on an MCP server.
McpListTools { id, server_label, tools, 3 more } A list of tools available on an MCP server.
A list of tools available on an MCP server.
McpApprovalRequest { id, arguments, name, 3 more } A request for human approval of a tool invocation.
A request for human approval of a tool invocation.
McpApprovalResponse { id, approval_request_id, approve, 3 more } A response to an MCP approval request.
A response to an MCP approval request.
BetaResponseCustomToolCall { call_id, input, name, 5 more } A call to a custom tool created by the model.
A call to a custom tool created by the model.
BetaResponseCustomToolCallOutputItem extends BetaResponseCustomToolCallOutput { call_id, output, type, 3 more } { id, status, created_by } The output of a custom tool call from your code, being sent back to the model.
The output of a custom tool call from your code, being sent back to the model.
BetaComputerAction = Click { button, type, x, 2 more } | DoubleClick { keys, type, x, y } | Drag { path, type, keys } | 6 moreA click action.
A click action.
Click { button, type, x, 2 more } A click action.
A click action.
DoubleClick { keys, type, x, y } A double click action.
A double click action.
Drag { path, type, keys } A drag action.
A drag action.
Flattened batched actions for computer_use. Each action includes an
type discriminator and action-specific fields.
Flattened batched actions for computer_use. Each action includes an
type discriminator and action-specific fields.
Click { button, type, x, 2 more } A click action.
A click action.
DoubleClick { keys, type, x, y } A double click action.
A double click action.
Drag { path, type, keys } A drag action.
A drag action.
BetaComputerTool { type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
BetaComputerUsePreviewTool { display_height, display_width, environment, type } A tool that controls a virtual computer. Learn more about the computer tool.
A tool that controls a virtual computer. Learn more about the computer tool.
BetaContainerAuto { type, file_ids, memory_limit, 2 more }
network_policy?: BetaContainerNetworkPolicyDisabled { type } | BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
skills?: Array<BetaSkillReference { skill_id, type, version } | BetaInlineSkill { description, name, source, type } >An optional list of skills referenced by id or inline data.
An optional list of skills referenced by id or inline data.
BetaCustomTool { name, type, allowed_callers, 3 more } A custom tool that processes input using a specified format. Learn more about custom tools
A custom tool that processes input using a specified format. Learn more about custom tools
BetaEasyInputMessage { content, role, phase, 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.
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.
Text, image, or audio input to the model, used to generate a response.
Can also contain previous assistant responses.
Text, image, or audio input to the model, used to generate a response. Can also contain previous assistant responses.
A list of one or many input items to the model, containing different content
types.
A list of one or many input items to the model, containing different content types.
BetaResponseInputImage { detail, type, file_id, 2 more } An image input to the model. Learn about image inputs.
An image input to the model. Learn about image inputs.
BetaResponseInputFile { type, detail, file_data, 4 more } A file input to the model.
A file input to the model.
detail?: "auto" | "low" | "high"The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.
The detail level of the file to be sent to the model. Use auto to let the system select the detail level; for GPT-5.6 and later models, auto uses high-quality rendering, which may increase input token usage. Use low for lower-cost rendering, or high to render the file at higher quality. Defaults to auto.
role: "user" | "assistant" | "system" | "developer"The role of the message input. One of user, assistant, system, or
developer.
The role of the message input. One of user, assistant, system, or
developer.
Labels an assistant message as intermediate commentary (commentary) or the final answer (final_answer).
For models like gpt-5.3-codex and beyond, when sending follow-up requests, preserve and resend
phase on all assistant messages — dropping it can degrade performance. Not used for user messages.
BetaFileSearchTool { type, vector_store_ids, filters, 2 more } A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
A tool that searches for relevant content from uploaded files. Learn more about the file search tool.
filters?: ComparisonFilter { key, type, value } | CompoundFilter { filters, type } | nullA filter to apply.
A filter to apply.
ComparisonFilter { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
CompoundFilter { filters, type } Combine multiple filters using and or or.
Combine multiple filters using and or or.
filters: Array<ComparisonFilter { key, type, value } | unknown>Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
Array of filters to combine. Items can be ComparisonFilter or CompoundFilter.
ComparisonFilter { key, type, value } A filter used to compare a specified attribute key to a given value using a defined comparison operation.
A filter used to compare a specified attribute key to a given value using a defined comparison operation.
The maximum number of results to return. This number should be between 1 and 50 inclusive.
ranking_options?: RankingOptions { hybrid_search, ranker, score_threshold } Ranking options for search.
Ranking options for search.
BetaFunctionShellTool { type, allowed_callers, environment } A tool that allows the model to execute shell commands.
A tool that allows the model to execute shell commands.
environment?: BetaContainerAuto { type, file_ids, memory_limit, 2 more } | BetaLocalEnvironment { type, skills } | BetaContainerReference { container_id, type } | null
BetaContainerAuto { type, file_ids, memory_limit, 2 more }
network_policy?: BetaContainerNetworkPolicyDisabled { type } | BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets } Network access policy for the container.
Network access policy for the container.
skills?: Array<BetaSkillReference { skill_id, type, version } | BetaInlineSkill { description, name, source, type } >An optional list of skills referenced by id or inline data.
An optional list of skills referenced by id or inline data.