Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Voice & Audio Production API reference
API Dashboard
Try ChatGPT
API Reference

Beta

BetaAssistants

Build Assistants that can call models and use tools.

Create assistant
Deprecated
$ openai beta:assistants create
POST/assistants
Delete assistant
Deprecated
$ openai beta:assistants delete
DELETE/assistants/{assistant_id}
List assistants
Deprecated
$ openai beta:assistants list
GET/assistants
Retrieve assistant
Deprecated
$ openai beta:assistants retrieve
GET/assistants/{assistant_id}
Modify assistant
Deprecated
$ openai beta:assistants update
POST/assistants/{assistant_id}
ModelsExpand Collapse
assistant: object { id, created_at, description, 10 more }

Represents an assistant that can call the model and use tools.

assistant_deleted: object { id, deleted, object }
assistant_stream_event: object { data, event, enabled } or object { data, event } or object { data, event } or 21 more

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.

assistant_tool: CodeInterpreterTool { type } or FileSearchTool { type, file_search } or FunctionTool { function, type }
code_interpreter_tool: object { type }
file_search_tool: object { type, file_search }
function_tool: object { function, type }
message_stream_event: object { data, event } or object { data, event } or object { data, event } or 2 more

Occurs when a message is created.

run_step_stream_event: object { data, event } or object { data, event } or object { data, event } or 4 more

Occurs when a run step is created.

run_stream_event: object { data, event } or object { data, event } or object { data, event } or 7 more

Occurs when a new run is created.

thread_stream_event: object { data, event, enabled }

Occurs when a new thread is created.

BetaChatKit

ModelsExpand Collapse
chatkit_workflow: object { id, state_variables, tracing, version }

Workflow metadata and state returned for the session.

BetaChatKitSessions

Cancel chat session
$ openai beta:chatkit:sessions cancel
POST/chatkit/sessions/{session_id}/cancel
Create ChatKit session
$ openai beta:chatkit:sessions create
POST/chatkit/sessions

BetaChatKitThreads

Delete ChatKit thread
$ openai beta:chatkit:threads delete
DELETE/chatkit/threads/{thread_id}
List ChatKit threads
$ openai beta:chatkit:threads list
GET/chatkit/threads
List ChatKit thread items
$ openai beta:chatkit:threads list-items
GET/chatkit/threads/{thread_id}/items
Retrieve ChatKit thread
$ openai beta:chatkit:threads retrieve
GET/chatkit/threads/{thread_id}
ModelsExpand Collapse
chat_session: object { id, chatkit_configuration, client_secret, 7 more }

Represents a ChatKit session and its resolved configuration.

chat_session_automatic_thread_titling: object { enabled }

Automatic thread title preferences for the session.

chat_session_chatkit_configuration: object { automatic_thread_titling, file_upload, history }

ChatKit configuration for the session.

chat_session_chatkit_configuration_param: object { automatic_thread_titling, file_upload, history }

Optional per-session configuration settings for ChatKit behavior.

chat_session_expires_after_param: object { anchor, seconds }

Controls when the session expires relative to an anchor timestamp.

chat_session_file_upload: object { enabled, max_file_size, max_files }

Upload permissions and limits applied to the session.

chat_session_history: object { enabled, recent_threads }

History retention preferences returned for the session.

chat_session_rate_limits: object { max_requests_per_1_minute }

Active per-minute request limit for the session.

chat_session_rate_limits_param: object { max_requests_per_1_minute }

Controls request rate limits for the session.

chat_session_status: "active" or "expired" or "cancelled"
chat_session_workflow_param: object { id, state_variables, tracing, version }

Workflow reference and overrides applied to the chat session.

chatkit_attachment: object { id, mime_type, name, 2 more }

Attachment metadata included on thread items.

chatkit_response_output_text: object { annotations, text, type }

Assistant response text accompanied by optional annotations.

chatkit_thread: object { id, created_at, object, 3 more }

Represents a ChatKit thread and its current status.

chatkit_thread_assistant_message_item: object { id, content, created_at, 3 more }

Assistant-authored message within a thread.

chatkit_thread_item_list: object { data, first_id, has_more, 2 more }

A paginated list of thread items rendered for the ChatKit API.

chatkit_thread_user_message_item: object { id, attachments, content, 5 more }

User-authored messages within a thread.

chatkit_widget_item: object { id, created_at, object, 3 more }

Thread item that renders a widget payload.

BetaResponses

Cancel a response
$ openai beta:responses cancel
POST/responses/{response_id}/cancel
Compact a response
$ openai beta:responses compact
POST/responses/compact
Create a model response
$ openai beta:responses create
POST/responses
Delete a model response
$ openai beta:responses delete
DELETE/responses/{response_id}
Get a model response
$ openai beta:responses retrieve
GET/responses/{response_id}
ModelsExpand Collapse
beta_apply_patch_tool: object { type, allowed_callers }

Allows the assistant to create, delete, or update files using unified diffs.

beta_compacted_response: object { id, created_at, object, 2 more }
beta_computer_action: object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more

A click action.

beta_computer_action_list: array of BetaComputerAction

Flattened batched actions for computer_use. Each action includes an type discriminator and action-specific fields.

beta_computer_tool: object { type }

A tool that controls a virtual computer. Learn more about the computer tool.

beta_computer_use_preview_tool: object { display_height, display_width, environment, type }

A tool that controls a virtual computer. Learn more about the computer tool.

beta_container_auto: object { type, file_ids, memory_limit, 2 more }
beta_container_network_policy_allowlist: object { allowed_domains, type, domain_secrets }
beta_container_network_policy_disabled: object { type }
beta_container_network_policy_domain_secret: object { domain, name, value }
beta_container_reference: object { container_id, type }
beta_custom_tool: object { name, type, allowed_callers, 3 more }

A custom tool that processes input using a specified format. Learn more about custom tools

beta_easy_input_message: object { 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.

beta_file_search_tool: object { type, vector_store_ids, filters, 2 more }

A tool that searches for relevant content from uploaded files. Learn more about the file search tool.

beta_function_shell_tool: object { type, allowed_callers, environment }

A tool that allows the model to execute shell commands.

beta_function_tool: object { name, parameters, strict, 5 more }

Defines a function in your own code the model can choose to call. Learn more about function calling.

beta_inline_skill: object { description, name, source, type }
beta_inline_skill_source: object { data, media_type, type }

Inline skill payload

beta_local_environment: object { type, skills }
beta_local_skill: object { description, name, path }
beta_mcp_tool_call_error: object { code, message, type } or object { content, type } or object { code, message, type }
beta_namespace_tool: object { description, name, tools, type }

Groups function/custom tools under a shared namespace.

beta_response: object { id, created_at, error, 31 more }
beta_response_apply_patch_tool_call: object { id, call_id, operation, 5 more }

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

beta_response_apply_patch_tool_call_output: object { id, call_id, status, 5 more }

The output emitted by an apply patch tool call.

beta_response_audio_delta_event: object { delta, sequence_number, type, agent }

Emitted when there is a partial audio response.

beta_response_audio_done_event: object { sequence_number, type, agent }

Emitted when the audio response is complete.

beta_response_audio_transcript_delta_event: object { delta, sequence_number, type, agent }

Emitted when there is a partial transcript of audio.

beta_response_audio_transcript_done_event: object { sequence_number, type, agent }

Emitted when the full audio transcript is completed.

beta_response_code_interpreter_call_code_delta_event: object { delta, item_id, output_index, 3 more }

Emitted when a partial code snippet is streamed by the code interpreter.

beta_response_code_interpreter_call_code_done_event: object { code, item_id, output_index, 3 more }

Emitted when the code snippet is finalized by the code interpreter.

beta_response_code_interpreter_call_completed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when the code interpreter call is completed.

beta_response_code_interpreter_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when a code interpreter call is in progress.

beta_response_code_interpreter_call_interpreting_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when the code interpreter is actively interpreting the code snippet.

beta_response_code_interpreter_tool_call: object { id, code, container_id, 4 more }

A tool call to run code.

beta_response_compaction_item: object { id, encrypted_content, type, 2 more }

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

beta_response_compaction_item_param: object { encrypted_content, type, id, agent }

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

beta_response_completed_event: object { response, sequence_number, type, agent }

Emitted when the model response is complete.

beta_response_computer_tool_call: object { id, call_id, pending_safety_checks, 5 more }

A tool call to a computer use tool. See the computer use guide for more information.

beta_response_computer_tool_call_output_item: object { id, call_id, output, 5 more }
beta_response_computer_tool_call_output_screenshot: object { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

beta_response_container_reference: object { container_id, type }

Represents a container created with /v1/containers.

beta_response_content: BetaResponseInputText { text, type, prompt_cache_breakpoint } or BetaResponseInputImage { detail, type, file_id, 2 more } or BetaResponseInputFile { type, detail, file_data, 4 more } or 3 more

Multi-modal input and output contents.

beta_response_content_part_added_event: object { content_index, item_id, output_index, 4 more }

Emitted when a new content part is added.

beta_response_content_part_done_event: object { content_index, item_id, output_index, 4 more }

Emitted when a content part is done.

beta_response_conversation_param: object { id }

The conversation that this response belongs to.

beta_response_created_event: object { response, sequence_number, type, agent }

An event that is emitted when a response is created.

beta_response_custom_tool_call: object { call_id, input, name, 5 more }

A call to a custom tool created by the model.

beta_response_custom_tool_call_input_delta_event: object { delta, item_id, output_index, 3 more }

Event representing a delta (partial update) to the input of a custom tool call.

beta_response_custom_tool_call_input_done_event: object { input, item_id, output_index, 3 more }

Event indicating that input for a custom tool call is complete.

beta_response_custom_tool_call_item: BetaResponseCustomToolCall { call_id, input, name, 5 more }

A call to a custom tool created by the model.

beta_response_custom_tool_call_output: object { call_id, output, type, 3 more }

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

beta_response_custom_tool_call_output_item: BetaResponseCustomToolCallOutput { call_id, output, type, 3 more }

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

beta_response_error: object { code, message }

An error object returned when the model fails to generate a Response.

beta_response_error_event: object { code, message, param, 3 more }

Emitted when an error occurs.

beta_response_failed_event: object { response, sequence_number, type, agent }

An event that is emitted when a response fails.

beta_response_file_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when a file search call is completed (results found).

beta_response_file_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when a file search call is initiated.

beta_response_file_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when a file search is currently searching.

beta_response_file_search_tool_call: object { id, queries, status, 3 more }

The results of a file search tool call. See the file search guide for more information.

beta_response_format_text_config: object { type } or BetaResponseFormatTextJSONSchemaConfig { name, schema, type, 2 more } or object { type }

An object specifying the format that the model must output.

Configuring { "type": "json_schema" } enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

The default format is { "type": "text" } with no additional options.

Not recommended for gpt-4o and newer models:

Setting to { "type": "json_object" } enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.

beta_response_format_text_json_schema_config: object { name, schema, type, 2 more }

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

beta_response_function_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }

Emitted when there is a partial function-call arguments delta.

beta_response_function_call_arguments_done_event: object { arguments, item_id, name, 4 more }

Emitted when function-call arguments are finalized.

beta_response_function_call_output_item: BetaResponseInputTextContent { text, type, prompt_cache_breakpoint } or BetaResponseInputImageContent { type, detail, file_id, 2 more } or BetaResponseInputFileContent { type, detail, file_data, 4 more }

A piece of message content, such as text, an image, or a file.

beta_response_function_call_output_item_list: array of BetaResponseFunctionCallOutputItem

An array of content outputs (text, image, file) for the function tool call.

beta_response_function_shell_call_output_content: object { outcome, stderr, stdout }

Captured stdout and stderr for a portion of a shell tool call output.

beta_response_function_shell_tool_call: object { id, action, call_id, 6 more }

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

beta_response_function_shell_tool_call_output: object { id, call_id, max_output_length, 6 more }

The output of a shell tool call that was emitted.

beta_response_function_tool_call: object { arguments, call_id, name, 6 more }

A tool call to run a function. See the function calling guide for more information.

beta_response_function_tool_call_item: BetaResponseFunctionToolCall { arguments, call_id, name, 6 more }

A tool call to run a function. See the function calling guide for more information.

beta_response_function_tool_call_output_item: object { id, output, status, 7 more }
beta_response_image_gen_call_completed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when an image generation tool call has completed and the final image is available.

beta_response_image_gen_call_generating_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when an image generation tool call is actively generating an image (intermediate state).

beta_response_image_gen_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when an image generation tool call is in progress.

beta_response_image_gen_call_partial_image_event: object { item_id, output_index, partial_image_b64, 8 more }

Emitted when a partial image is available during image generation streaming.

beta_response_in_progress_event: object { response, sequence_number, type, agent }

Emitted when the response is in progress.

beta_response_includable: "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more

Specify additional output data to include in the model response. Currently supported values are:

  • web_search_call.results: Include the search results of the web search tool call.
  • web_search_call.action.sources: Include the sources of the web search tool call.
  • code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items.
  • computer_call_output.output.image_url: Include image urls from the computer call output.
  • file_search_call.results: Include the search results of the file search tool call.
  • message.input_image.image_url: Include image urls from the input message.
  • message.output_text.logprobs: Include logprobs with assistant messages.
  • reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program).
beta_response_incomplete_event: object { response, sequence_number, type, agent }

An event that is emitted when a response finishes as incomplete.

beta_response_inject_created_event: object { response_id, sequence_number, type, stream_id }

Emitted when all injected input items were validated and committed to the active response.

beta_response_inject_event: object { input, response_id, type }

Injects input items into an active response over a WebSocket connection. The items are validated and committed atomically. Currently, the server accepts client-owned tool outputs that resume a waiting agent.

beta_response_inject_failed_event: object { error, input, response_id, 3 more }

Emitted when injected input could not be committed to a response. The event returns the uncommitted raw input so the client can retry it in another response when appropriate.

beta_response_input: array of BetaResponseInputItem

A list of one or many input items to the model, containing different content types.

beta_response_input_audio: object { input_audio, type }

An audio input to the model.

beta_response_input_content: BetaResponseInputText { text, type, prompt_cache_breakpoint } or BetaResponseInputImage { detail, type, file_id, 2 more } or BetaResponseInputFile { type, detail, file_data, 4 more }

A text input to the model.

beta_response_input_file: object { type, detail, file_data, 4 more }

A file input to the model.

beta_response_input_file_content: object { type, detail, file_data, 4 more }

A file input to the model.

beta_response_input_image: object { detail, type, file_id, 2 more }

An image input to the model. Learn about image inputs.

beta_response_input_image_content: object { type, detail, file_id, 2 more }

An image input to the model. Learn about image inputs

beta_response_input_item: BetaEasyInputMessage { content, role, phase, type } or object { content, role, agent, 2 more } or BetaResponseOutputMessage { id, content, role, 4 more } or 32 more

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.

beta_response_input_message_content_list: array of BetaResponseInputContent

A list of one or many input items to the model, containing different content types.

beta_response_input_message_item: object { id, content, role, 3 more }
beta_response_input_text: object { text, type, prompt_cache_breakpoint }

A text input to the model.

beta_response_input_text_content: object { text, type, prompt_cache_breakpoint }

A text input to the model.

beta_response_item: BetaResponseInputMessageItem { id, content, role, 3 more } or BetaResponseOutputMessage { id, content, role, 4 more } or BetaResponseFileSearchToolCall { id, queries, status, 3 more } or 29 more

Content item used to generate a response.

beta_response_local_environment: object { type }

Represents the use of a local environment to perform shell actions.

beta_response_mcp_call_arguments_delta_event: object { delta, item_id, output_index, 3 more }

Emitted when there is a delta (partial update) to the arguments of an MCP tool call.

beta_response_mcp_call_arguments_done_event: object { arguments, item_id, output_index, 3 more }

Emitted when the arguments for an MCP tool call are finalized.

beta_response_mcp_call_completed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call has completed successfully.

beta_response_mcp_call_failed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call has failed.

beta_response_mcp_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call is in progress.

beta_response_mcp_list_tools_completed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when the list of available MCP tools has been successfully retrieved.

beta_response_mcp_list_tools_failed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when the attempt to list available MCP tools has failed.

beta_response_mcp_list_tools_in_progress_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when the system is in the process of retrieving the list of available MCP tools.

beta_response_output_audio: object { data, transcript, type }

An audio output from the model.

beta_response_output_item: BetaResponseOutputMessage { id, content, role, 4 more } or BetaResponseFileSearchToolCall { id, queries, status, 3 more } or BetaResponseFunctionToolCall { arguments, call_id, name, 6 more } or 28 more

An output message from the model.

beta_response_output_item_added_event: object { item, output_index, sequence_number, 2 more }

Emitted when a new output item is added.

beta_response_output_item_done_event: object { item, output_index, sequence_number, 2 more }

Emitted when an output item is marked done.

beta_response_output_message: object { id, content, role, 4 more }

An output message from the model.

beta_response_output_refusal: object { refusal, type }

A refusal from the model.

beta_response_output_text: object { annotations, text, type, logprobs }

A text output from the model.

beta_response_output_text_annotation_added_event: object { annotation, annotation_index, content_index, 5 more }

Emitted when an annotation is added to output text content.

beta_response_prompt: object { id, variables, version }

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

beta_response_queued_event: object { response, sequence_number, type, agent }

Emitted when a response is queued and waiting to be processed.

beta_response_reasoning_item: object { 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.

beta_response_reasoning_summary_part_added_event: object { item_id, output_index, part, 4 more }

Emitted when a new reasoning summary part is added.

beta_response_reasoning_summary_part_done_event: object { item_id, output_index, part, 5 more }

Emitted when a reasoning summary part is completed.

beta_response_reasoning_summary_text_delta_event: object { delta, item_id, output_index, 4 more }

Emitted when a delta is added to a reasoning summary text.

beta_response_reasoning_summary_text_done_event: object { item_id, output_index, sequence_number, 4 more }

Emitted when a reasoning summary text is completed.

beta_response_reasoning_text_delta_event: object { content_index, delta, item_id, 4 more }

Emitted when a delta is added to a reasoning text.

beta_response_reasoning_text_done_event: object { content_index, item_id, output_index, 4 more }

Emitted when a reasoning text is completed.

beta_response_refusal_delta_event: object { content_index, delta, item_id, 4 more }

Emitted when there is a partial refusal text.

beta_response_refusal_done_event: object { content_index, item_id, output_index, 4 more }

Emitted when refusal text is finalized.

beta_response_shell_call_command_added_event: object { command, command_index, output_index, 3 more }

A streaming event that indicated a shell command was added to a tool call.

beta_response_shell_call_command_delta_event: object { command_index, delta, output_index, 4 more }

A streaming event that indicated a shell command was incrementally updated.

beta_response_shell_call_command_done_event: object { command, command_index, output_index, 3 more }

A streaming event that indicated a shell command was completed.

beta_response_shell_call_output_content_delta_event: object { command_index, delta, item_id, 4 more }

A streaming event that indicated shell call output was incrementally added.

beta_response_shell_call_output_content_done_event: object { command_index, item_id, output, 4 more }

A streaming event that indicated shell call output was completed.

beta_response_status: "completed" or "failed" or "in_progress" or 3 more

The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete.

beta_response_stream_event: BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } or BetaResponseAudioDoneEvent { sequence_number, type, agent } or BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } or 55 more

Event emitted while a response is streamed.

beta_response_text_config: object { format, verbosity }

Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more:

beta_response_text_delta_event: object { content_index, delta, item_id, 5 more }

Emitted when there is an additional text delta.

beta_response_text_done_event: object { content_index, item_id, logprobs, 5 more }

Emitted when text content is finalized.

beta_response_tool_search_call: object { id, arguments, call_id, 5 more }
beta_response_tool_search_output_item: object { id, call_id, execution, 5 more }
beta_response_tool_search_output_item_param: object { tools, type, id, 4 more }
beta_response_usage: object { input_tokens, input_tokens_details, output_tokens, 2 more }

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

beta_response_web_search_call_completed_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is completed.

beta_response_web_search_call_in_progress_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is initiated.

beta_response_web_search_call_searching_event: object { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is executing.

beta_responses_client_event: object { type, background, context_management, 31 more } or BetaResponseInjectEvent { input, response_id, type }

Client events accepted by the Responses WebSocket server.

beta_responses_server_event: BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } or BetaResponseAudioDoneEvent { sequence_number, type, agent } or BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } or 57 more

Server events emitted by the Responses WebSocket server.

beta_skill_reference: object { skill_id, type, version }
beta_tool: BetaFunctionTool { name, parameters, strict, 5 more } or BetaFileSearchTool { type, vector_store_ids, filters, 2 more } or BetaComputerTool { type } or 13 more

A tool that can be used to generate a response.

beta_tool_choice_allowed: object { mode, tools, type }

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

beta_tool_choice_apply_patch: object { type }

Forces the model to call the apply_patch tool when executing a tool call.

beta_tool_choice_custom: object { name, type }

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

beta_tool_choice_function: object { name, type }

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

beta_tool_choice_mcp: object { server_label, type, name }

Use this option to force the model to call a specific tool on a remote MCP server.

beta_tool_choice_options: "none" or "auto" or "required"

Controls which (if any) tool is called by the model.

none means the model will not call any tool and instead generates a message.

auto 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.

beta_tool_choice_shell: object { type }

Forces the model to call the shell tool when a tool call is required.

beta_tool_choice_types: object { type }

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

beta_tool_search_tool: object { type, description, execution, parameters }

Hosted or BYOT tool search configuration for deferred tools.

beta_web_search_preview_tool: object { 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.

beta_web_search_tool: object { type, external_web_access, filters, 2 more }

Search the Internet for sources related to the prompt. Learn more about the web search tool.

BetaResponsesInput Items

List input items
$ openai beta:responses:input-items list
GET/responses/{response_id}/input_items
ModelsExpand Collapse
beta_responseItemList: object { data, first_id, has_more, 2 more }

A list of Response items.

BetaResponsesInput Tokens

Get input token counts
$ openai beta:responses:input-tokens count
POST/responses/input_tokens

BetaThreads

Build Assistants that can call models and use tools.

Create thread
Deprecated
$ openai beta:threads create
POST/threads
Create thread and run
Deprecated
$ openai beta:threads create-and-run
POST/threads/runs
Delete thread
Deprecated
$ openai beta:threads delete
DELETE/threads/{thread_id}
Retrieve thread
Deprecated
$ openai beta:threads retrieve
GET/threads/{thread_id}
Modify thread
Deprecated
$ openai beta:threads update
POST/threads/{thread_id}
ModelsExpand Collapse
assistant_response_format_option: "auto" or ResponseFormatText { type } or ResponseFormatJSONObject { type } or 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.

assistant_tool_choice: object { type, function }

Specifies a tool the model should use. Use to force the model to call a specific tool.

assistant_tool_choice_function: object { name }
assistant_tool_choice_option: "none" or "auto" or "required" or AssistantToolChoice { type, function }

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: object { id, created_at, metadata, 2 more }

Represents a thread that contains messages.

thread_deleted: object { id, deleted, object }

BetaThreadsMessages

Build Assistants that can call models and use tools.

Create message
Deprecated
$ openai beta:threads:messages create
POST/threads/{thread_id}/messages
Delete message
Deprecated
$ openai beta:threads:messages delete
DELETE/threads/{thread_id}/messages/{message_id}
List messages
Deprecated
$ openai beta:threads:messages list
GET/threads/{thread_id}/messages
Retrieve message
Deprecated
$ openai beta:threads:messages retrieve
GET/threads/{thread_id}/messages/{message_id}
Modify message
Deprecated
$ openai beta:threads:messages update
POST/threads/{thread_id}/messages/{message_id}
ModelsExpand Collapse
annotation: FileCitationAnnotation { end_index, file_citation, start_index, 2 more } or FilePathAnnotation { end_index, file_path, start_index, 2 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.

annotation_delta: FileCitationDeltaAnnotation { index, type, end_index, 3 more } or FilePathDeltaAnnotation { 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.

file_citation_annotation: object { end_index, file_citation, start_index, 2 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.

file_citation_delta_annotation: object { 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.

file_path_annotation: object { end_index, file_path, start_index, 2 more }

A URL for the file that’s generated when the assistant used the code_interpreter tool to generate a file.

file_path_delta_annotation: object { index, type, end_index, 3 more }

A URL for the file that’s generated when the assistant used the code_interpreter tool to generate a file.

image_file: object { file_id, detail }
image_file_content_block: object { image_file, type }

References an image File in the content of a message.

image_file_delta: object { detail, file_id }
image_file_delta_block: object { index, type, image_file }

References an image File in the content of a message.

image_url: object { url, detail }
image_url_content_block: object { image_url, type }

References an image URL in the content of a message.

image_url_delta: object { detail, url }
image_url_delta_block: object { index, type, image_url }

References an image URL in the content of a message.

message: object { id, assistant_id, attachments, 11 more }

Represents a message within a thread.

message_content: ImageFileContentBlock { image_file, type } or ImageURLContentBlock { image_url, type } or TextContentBlock { text, type } or RefusalContentBlock { refusal, type }

References an image File in the content of a message.

message_content_delta: ImageFileDeltaBlock { index, type, image_file } or TextDeltaBlock { index, type, text } or RefusalDeltaBlock { index, type, refusal } or ImageURLDeltaBlock { index, type, image_url }

References an image File in the content of a message.

message_content_part_param: ImageFileContentBlock { image_file, type } or ImageURLContentBlock { image_url, type } or TextContentBlockParam { text, type }

References an image File in the content of a message.

message_deleted: object { id, deleted, object }
message_delta: object { content, role }

The delta containing the fields that have changed on the Message.

message_delta_event: object { id, delta, object }

Represents a message delta i.e. any changed fields on a message during streaming.

refusal_content_block: object { refusal, type }

The refusal content generated by the assistant.

refusal_delta_block: object { index, type, refusal }

The refusal content that is part of a message.

text: object { annotations, value }
text_content_block: object { text, type }

The text content that is part of a message.

text_content_block_param: object { text, type }

The text content that is part of a message.

text_delta: object { annotations, value }
text_delta_block: object { index, type, text }

The text content that is part of a message.

BetaThreadsRuns

Build Assistants that can call models and use tools.

Cancel a run
Deprecated
$ openai beta:threads:runs cancel
POST/threads/{thread_id}/runs/{run_id}/cancel
Create run
Deprecated
$ openai beta:threads:runs create
POST/threads/{thread_id}/runs
List runs
Deprecated
$ openai beta:threads:runs list
GET/threads/{thread_id}/runs
Retrieve run
Deprecated
$ openai beta:threads:runs retrieve
GET/threads/{thread_id}/runs/{run_id}
Submit tool outputs to run
Deprecated
$ openai beta:threads:runs submit-tool-outputs
POST/threads/{thread_id}/runs/{run_id}/submit_tool_outputs
Modify run
Deprecated
$ openai beta:threads:runs update
POST/threads/{thread_id}/runs/{run_id}
ModelsExpand Collapse
required_action_function_tool_call: object { id, function, type }

Tool call objects

run: object { id, assistant_id, cancelled_at, 24 more }

Represents an execution run on a thread.

run_status: "queued" or "in_progress" or "requires_action" or 6 more

The status of the run, which can be either queued, in_progress, requires_action, cancelling, cancelled, failed, completed, incomplete, or expired.

BetaThreadsRunsSteps

Build Assistants that can call models and use tools.

List run steps
Deprecated
$ openai beta:threads:runs:steps list
GET/threads/{thread_id}/runs/{run_id}/steps
Retrieve run step
Deprecated
$ openai beta:threads:runs:steps retrieve
GET/threads/{thread_id}/runs/{run_id}/steps/{step_id}
ModelsExpand Collapse
code_interpreter_logs: object { index, type, logs }

Text output from the Code Interpreter tool call as part of a run step.

code_interpreter_output_image: object { index, type, image }
code_interpreter_tool_call: object { id, code_interpreter, type }

Details of the Code Interpreter tool call the run step was involved in.

code_interpreter_tool_call_delta: object { index, type, id, code_interpreter }

Details of the Code Interpreter tool call the run step was involved in.

file_search_tool_call: object { id, file_search, type }
file_search_tool_call_delta: object { file_search, index, type, id }
function_tool_call: object { id, function, type }
function_tool_call_delta: object { index, type, id, function }
message_creation_step_details: object { message_creation, type }

Details of the message creation by the run step.

run_step: object { id, assistant_id, cancelled_at, 13 more }

Represents a step in execution of a run.

run_step_delta: object { step_details }

The delta containing the fields that have changed on the run step.

run_step_delta_event: object { id, delta, object }

Represents a run step delta i.e. any changed fields on a run step during streaming.

run_step_delta_message_delta: object { type, message_creation }

Details of the message creation by the run step.

run_step_include: "step_details.tool_calls[*].file_search.results[*].content"
tool_call: CodeInterpreterToolCall { id, code_interpreter, type } or FileSearchToolCall { id, file_search, type } or FunctionToolCall { id, function, type }

Details of the Code Interpreter tool call the run step was involved in.

tool_call_delta: CodeInterpreterToolCallDelta { index, type, id, code_interpreter } or FileSearchToolCallDelta { file_search, index, type, id } or FunctionToolCallDelta { index, type, id, function }

Details of the Code Interpreter tool call the run step was involved in.

tool_call_delta_object: object { type, tool_calls }

Details of the tool call.

tool_calls_step_details: object { tool_calls, type }

Details of the tool call.