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

Threads

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 }

ThreadsMessages

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.

ThreadsRuns

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.

ThreadsRunsSteps

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.