API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Threads

Build Assistants that can call models and use tools.

Create thread

Deprecated

beta.threads.create(**kwargs) -> Thread { id, created_at, metadata, 2 more }

POST/threads

Create thread and run

Deprecated

beta.threads.create_and_run(**kwargs) -> Run { id, assistant_id, cancelled_at, 24 more }

POST/threads/runs

Delete thread

Deprecated

beta.threads.delete(thread_id) -> ThreadDeleted { id, deleted, object }

DELETE/threads/{thread_id}

Retrieve thread

Deprecated

beta.threads.retrieve(thread_id) -> Thread { id, created_at, metadata, 2 more }

GET/threads/{thread_id}

Modify thread

Deprecated

beta.threads.update(thread_id, **kwargs) -> Thread { id, created_at, metadata, 2 more }

POST/threads/{thread_id}

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.

class AssistantToolChoice { type, function }

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

class AssistantToolChoiceFunction { name }

AssistantToolChoiceOption = :none | :auto | :required | 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.

class Thread { id, created_at, metadata, 2 more }

Represents a thread that contains messages.

class ThreadDeleted { id, deleted, object }

ThreadsMessages

Build Assistants that can call models and use tools.

Create message

Deprecated

beta.threads.messages.create(thread_id, **kwargs) -> Message { id, assistant_id, attachments, 11 more }

POST/threads/{thread_id}/messages

Delete message

Deprecated

beta.threads.messages.delete(message_id, **kwargs) -> MessageDeleted { id, deleted, object }

DELETE/threads/{thread_id}/messages/{message_id}

List messages

Deprecated

beta.threads.messages.list(thread_id, **kwargs) -> CursorPage<Message { id, assistant_id, attachments, 11 more } >

GET/threads/{thread_id}/messages

Retrieve message

Deprecated

beta.threads.messages.retrieve(message_id, **kwargs) -> Message { id, assistant_id, attachments, 11 more }

GET/threads/{thread_id}/messages/{message_id}

Modify message

Deprecated

beta.threads.messages.update(message_id, **kwargs) -> Message { id, assistant_id, attachments, 11 more }

POST/threads/{thread_id}/messages/{message_id}

ModelsExpand Collapse

Annotation = FileCitationAnnotation { end_index, file_citation, start_index, 2 more } | 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.

AnnotationDelta = FileCitationDeltaAnnotation { index, type, end_index, 3 more } | 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.

class FileCitationAnnotation { 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.

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

class FilePathAnnotation { 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.

class FilePathDeltaAnnotation { 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.

class ImageFile { file_id, detail }

class ImageFileContentBlock { image_file, type }

References an image File in the content of a message.

class ImageFileDelta { detail, file_id }

class ImageFileDeltaBlock { index, type, image_file }

References an image File in the content of a message.

class ImageURL { url, detail }

class ImageURLContentBlock { image_url, type }

References an image URL in the content of a message.

class ImageURLDelta { detail, url }

class ImageURLDeltaBlock { index, type, image_url }

References an image URL in the content of a message.

class Message { id, assistant_id, attachments, 11 more }

Represents a message within a thread.

MessageContent = ImageFileContentBlock { image_file, type } | ImageURLContentBlock { image_url, type } | TextContentBlock { text, type } | RefusalContentBlock { refusal, type }

References an image File in the content of a message.

MessageContentDelta = ImageFileDeltaBlock { index, type, image_file } | TextDeltaBlock { index, type, text } | RefusalDeltaBlock { index, type, refusal } | ImageURLDeltaBlock { index, type, image_url }

References an image File in the content of a message.

MessageContentPartParam = ImageFileContentBlock { image_file, type } | ImageURLContentBlock { image_url, type } | TextContentBlockParam { text, type }

References an image File in the content of a message.

class MessageDeleted { id, deleted, object }

class MessageDelta { content, role }

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

class MessageDeltaEvent { id, delta, object }

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

class RefusalContentBlock { refusal, type }

The refusal content generated by the assistant.

class RefusalDeltaBlock { index, type, refusal }

The refusal content that is part of a message.

class Text { annotations, value }

class TextContentBlock { text, type }

The text content that is part of a message.

class TextContentBlockParam { text, type }

The text content that is part of a message.

class TextDelta { annotations, value }

class TextDeltaBlock { 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

beta.threads.runs.cancel(run_id, **kwargs) -> Run { id, assistant_id, cancelled_at, 24 more }

POST/threads/{thread_id}/runs/{run_id}/cancel

Create run

Deprecated

beta.threads.runs.create(thread_id, **kwargs) -> Run { id, assistant_id, cancelled_at, 24 more }

POST/threads/{thread_id}/runs

List runs

Deprecated

beta.threads.runs.list(thread_id, **kwargs) -> CursorPage<Run { id, assistant_id, cancelled_at, 24 more } >

GET/threads/{thread_id}/runs

Retrieve run

Deprecated

beta.threads.runs.retrieve(run_id, **kwargs) -> Run { id, assistant_id, cancelled_at, 24 more }

GET/threads/{thread_id}/runs/{run_id}

Submit tool outputs to run

Deprecated

beta.threads.runs.submit_tool_outputs(run_id, **kwargs) -> Run { id, assistant_id, cancelled_at, 24 more }

POST/threads/{thread_id}/runs/{run_id}/submit_tool_outputs

Modify run

Deprecated

beta.threads.runs.update(run_id, **kwargs) -> Run { id, assistant_id, cancelled_at, 24 more }

POST/threads/{thread_id}/runs/{run_id}

ModelsExpand Collapse

class RequiredActionFunctionToolCall { id, function, type }

Tool call objects

class Run { id, assistant_id, cancelled_at, 24 more }

Represents an execution run on a thread.

RunStatus = :queued | :in_progress | :requires_action | 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

beta.threads.runs.steps.list(run_id, **kwargs) -> CursorPage<RunStep { id, assistant_id, cancelled_at, 13 more } >

GET/threads/{thread_id}/runs/{run_id}/steps

Retrieve run step

Deprecated

beta.threads.runs.steps.retrieve(step_id, **kwargs) -> RunStep { id, assistant_id, cancelled_at, 13 more }

GET/threads/{thread_id}/runs/{run_id}/steps/{step_id}

ModelsExpand Collapse

class CodeInterpreterLogs { index, type, logs }

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

class CodeInterpreterOutputImage { index, type, image }

class CodeInterpreterToolCall { id, code_interpreter, type }

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

class CodeInterpreterToolCallDelta { index, type, id, code_interpreter }

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

class FileSearchToolCall { id, file_search, type }

class FileSearchToolCallDelta { file_search, index, type, id }

class FunctionToolCall { id, function, type }

class FunctionToolCallDelta { index, type, id, function }

class MessageCreationStepDetails { message_creation, type }

Details of the message creation by the run step.

class RunStep { id, assistant_id, cancelled_at, 13 more }

Represents a step in execution of a run.

class RunStepDelta { step_details }

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

class RunStepDeltaEvent { id, delta, object }

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

class RunStepDeltaMessageDelta { type, message_creation }

Details of the message creation by the run step.

RunStepInclude = :"step_details.tool_calls[*].file_search.results[*].content"

ToolCall = CodeInterpreterToolCall { id, code_interpreter, type } | FileSearchToolCall { id, file_search, type } | FunctionToolCall { id, function, type }

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

ToolCallDelta = CodeInterpreterToolCallDelta { index, type, id, code_interpreter } | FileSearchToolCallDelta { file_search, index, type, id } | FunctionToolCallDelta { index, type, id, function }

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

class ToolCallDeltaObject { type, tool_calls }

Details of the tool call.

class ToolCallsStepDetails { tool_calls, type }

Details of the tool call.