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 Audio & voice Production API reference

Beta

BetaAgents

Create an agent
beta.agents.create(**kwargs) -> Agent { id, created_at, instructions, 10 more }
POST/agents
Delete an agent
beta.agents.delete(agent_id) -> AgentDeleted { id, deleted, object }
DELETE/agents/{agent_id}
List agents
beta.agents.list(**kwargs) -> CursorPage<Agent { id, created_at, instructions, 10 more } >
GET/agents
Retrieve an agent
beta.agents.retrieve(agent_id) -> Agent { id, created_at, instructions, 10 more }
GET/agents/{agent_id}
Update an agent
beta.agents.update(agent_id, **kwargs) -> Agent { id, created_at, instructions, 10 more }
POST/agents/{agent_id}
ModelsExpand Collapse
class Agent { id, created_at, instructions, 10 more }

A reusable agent scoped to the caller’s project.

class AgentBrowserAuthenticationCancelParam { action, type }
class AgentBrowserAuthenticationSubmitParam { action, fields, type, selected_option }
class AgentBrowserOriginAccessParam { decision, type }
class AgentCloseSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

A request to close a subagent.

class AgentCommandExecutionItem { id, command, cwd, 6 more }

A command execution produced by the agent.

AgentContent = OutputText { text, type } | EncryptedContent{ encrypted_content, type}

A plaintext or encrypted content part exchanged between agents.

class AgentCreateSubagentCallItem { id, agent_id, content, 5 more }

A request to spawn a subagent.

class AgentDeleted { id, deleted, object }

A deleted reusable agent.

class AgentFunctionCallItem { id, arguments, call_id, 4 more }

A function call produced by the agent.

AgentFunctionCallOutput = String | Array[InputContent]

The text or model-input content supplied as a function result.

AgentFunctionCallOutputParam = String | Array[InputContentParam]

A function result represented as text or supported model-input content.

AgentFunctionCallStatus = :in_progress | :completed | :failed | :incomplete

The status of a tool call.

class AgentInterruptSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

A request to interrupt a subagent’s current turn. The subagent remains available.

class AgentMcpCallItem { id, arguments, error, 6 more }

A call to a tool on an MCP server.

class AgentOutputCommandExecutionOutputDeltaEvent { delta, event_id, item_id, 4 more }

Emitted when command execution produces an output delta.

AgentOutputItem = AgentSessionAssistantMessage { id, content, phase, 4 more } | AgentReasoningItem { id, status, summary, 2 more } | AgentFunctionCallItem { id, arguments, call_id, 4 more } | 11 more

An output item produced by an agent.

AgentOutputItemStatus = :in_progress | :completed | :incomplete

The status of an agent output item.

class AgentReasoning { effort, summary }

The reasoning configuration used by an agent.

class AgentReasoningItem { id, status, summary, 2 more }

A reasoning item produced by the agent.

class AgentReasoningParam { effort, summary }

Reasoning configuration for the agent.

class AgentResumeSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

A request to resume a subagent.

class AgentSendSubagentInputCallItem { id, content, recipient_agent_id, 4 more }

A request to send input to another agent.

class AgentSession { id, agent, created_at, 10 more }

A Managed Agents session.

class AgentSessionAssistantMessage { id, content, phase, 4 more }

An assistant message produced by the agent.

class AgentSessionCreatedEvent { event_id, session, type }

Emitted when a session is created.

class AgentSessionDeleted { id, deleted, object }

A Managed Agents session removed from the public API. Physical cleanup may continue asynchronously.

class AgentSessionEnvironmentConnectedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment connects.

class AgentSessionEnvironmentDisconnectedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment disconnects.

class AgentSessionEnvironmentExpiredEvent { environment, event_id, session_id, 2 more }

Emitted after a suspended hosted session environment and its checkpoint expire.

class AgentSessionEnvironmentFailedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment fails.

class AgentSessionEnvironmentPendingEvent { environment, event_id, session_id, 2 more }

Emitted while a session environment is being prepared.

class AgentSessionEnvironmentReadyEvent { environment, event_id, session_id, 2 more }

Emitted when a hosted session environment is ready to connect.

class AgentSessionEnvironmentResetEvent { environment_id, event_id, reset_count, 3 more }

Emitted after a hosted sandbox is replaced. Conversation history survives; changes to the previous sandbox’s files and processes do not.

class AgentSessionEnvironmentState { id, error, status, type }

The current state of a session environment.

class AgentSessionEnvironmentSuspendedEvent { environment, event_id, session_id, 2 more }

Emitted after an idle hosted session environment is checkpointed and stopped.

class AgentSessionErrorEvent { error, event_id, session_id, type }

Emitted when a turn or session fails.

AgentSessionEvent = AgentSessionErrorEvent { error, event_id, session_id, type } | AgentSessionEnvironmentReadyEvent { environment, event_id, session_id, 2 more } | AgentSessionEnvironmentSuspendedEvent { environment, event_id, session_id, 2 more } | 30 more

An event emitted by a Managed Agents session.

class AgentSessionFailedEvent { event_id, session, type }

Emitted when a session fails.

class AgentSessionIdleEvent { event_id, session, type }

Emitted when a session becomes idle.

class AgentSessionInProgressEvent { event_id, session, type }

Emitted when a session starts processing a turn.

class AgentSessionInputMessageParam { content, role, type }

A user message submitted to a session.

AgentSessionInputParam = AgentSessionInputComputerUseApprovalRequestResult{ request_id, response, type} | AgentSessionInputMessage{ input, type} | AgentSessionInputCancel{ type} | AgentSessionInputToolResult{ call_id, success, turn_id, 3 more}

Input submitted to an existing session.

AgentSessionItem = AgentSessionMessage { id, content, phase, 4 more } | AgentReasoningItem { id, status, summary, 2 more } | AgentFunctionCallItem { id, arguments, call_id, 4 more } | 14 more

An item associated with a session turn.

class AgentSessionMessage { id, content, phase, 4 more }

A user or assistant message recorded in a session.

AgentSessionMessageContent = InputText{ text, type} | InputImage{ image_url, type} | OutputText{ text, type}

A content part in a session message.

class AgentSessionRequiresActionEvent { event_id, session, type }

Emitted when a session is waiting for one or more required actions.

class AgentSessionSubagentActiveEvent { event_id, subagent, type }

Emitted when a closed subagent successfully resumes.

class AgentSessionSubagentClosedEvent { event_id, subagent, type }

Emitted when a subagent is closed.

class AgentSessionSubagentCreatedEvent { event_id, subagent, type }

Emitted when a subagent is created.

class AgentSessionTurnCancelledEvent { event_id, session_id, turn, 3 more }

Emitted when a turn is cancelled.

class AgentSessionTurnCompletedEvent { event_id, session_id, turn, 3 more }

Emitted when a turn completes.

class AgentSessionTurnContentPartAddedEvent { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is added.

class AgentSessionTurnContentPartDoneEvent { content_index, event_id, item_id, 5 more }

Emitted when an output content part is complete.

class AgentSessionTurnCreatedEvent { event_id, session_id, turn, 2 more }

Emitted when a turn is created.

class AgentSessionTurnFailedEvent { event_id, session_id, turn, 3 more }

Emitted when a turn fails.

class AgentSessionTurnInProgressEvent { event_id, session_id, turn, 2 more }

Emitted when a turn starts running.

class AgentSessionTurnItemAddedEvent { event_id, item, output_index, 3 more }

Emitted when an item is added to a turn.

class AgentSessionTurnItemDoneEvent { event_id, item, output_index, 3 more }

Emitted when an output item is complete.

class AgentSessionTurnOutputTextDeltaEvent { content_index, delta, event_id, 5 more }

Emitted when text is appended to an output text content part.

class AgentSessionTurnOutputTextDoneEvent { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is complete.

class AgentSessionTurnReasoningSummaryPartAddedEvent { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is added.

class AgentSessionTurnReasoningSummaryPartDoneEvent { event_id, item_id, output_index, 6 more }

Emitted when a reasoning summary part is complete.

class AgentSessionTurnReasoningSummaryTextDeltaEvent { delta, event_id, item_id, 5 more }

Emitted when text is appended to a reasoning summary.

class AgentSessionTurnReasoningSummaryTextDoneEvent { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is complete.

class AgentText { format_, verbosity }

The text configuration used by an agent.

class AgentTextParam { format_, verbosity }

Configuration for text generated by the agent.

AgentTool = Function{ defer_loading, description, name, 2 more} | ProgrammaticToolCalling{ enabled, type} | Mcp{ allowed_tools, connection_origin, credential_id, 5 more} | 2 more

A tool available to the agent.

AgentToolParam = Function{ description, name, parameters, 2 more} | ToolSearch{ type} | ProgrammaticToolCalling{ type, enabled} | 3 more

A tool available to the agent.

class AgentWaitForSubagentsCallItem { id, recipient_agent_ids, sender_agent_id, 3 more }

A request to wait for one or more subagents.

class AgentWebSearchCallItem { id, action, status, 2 more }

A web search call produced by the agent.

Environment = None{ type} | OpenAIHosted{ id, capability_directories, files, 7 more} | SelfHosted{ id, capability_directories, remote_url, 2 more}

The execution environment for a session.

EnvironmentParam = None{ type} | OpenAIHosted{ type, capability_directories, container_size, 10 more} | SelfHosted{ type, workspace_directory, capability_directories}

The execution environment and optional reusable template for a session.

HostedEnvironmentFile = HostedEnvironmentFileID { id, file_id, path, 2 more } | Inline{ id, path, size_bytes, type}

Metadata for a file materialized in an OpenAI-hosted execution environment.

class HostedEnvironmentFileID { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

HostedEnvironmentFileParam = FileID{ file_id, path, type} | Inline{ data, path, type}

A file materialized in an OpenAI-hosted execution environment.

class HostedPlugin { description, name, type }

A plugin installed from an inline ZIP archive.

class HostedPluginParam { description, name, source, type }

Supplies a plugin ZIP directly in the session request.

HostedSkill = HostedSkillReference { description, name, skill_id, 2 more } | Inline{ description, name, type}

A skill installed in an OpenAI-hosted environment.

HostedSkillParam = SkillReference{ skill_id, type, version} | Inline{ description, name, source, type}

A skill installed in an OpenAI-hosted environment.

class HostedSkillReference { description, name, skill_id, 2 more }

A skill installed from the Skills API.

class InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

InputContent = InputText{ text, type} | InputImage{ image_url, type}

User-provided content recorded in a session item.

InputContentParam = InputText{ text, type} | InputImage{ image_url, type}

Content included in an input message.

McpTransport = HTTP{ server_url, type} | Stdio{ args, command, cwd, 2 more}

The transport used to connect to an MCP server.

McpTransportParam = HTTP{ server_url, type, authorization, headers} | Stdio{ command, cwd, type, 3 more}

The transport used to connect to an MCP server.

class MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

class MultiAgentConfigParam { enabled, max_concurrent_subagents }

Explicit configuration for creating and coordinating subagents.

class OutputText { text, type }

A text content part produced by the agent.

PersistedAgentTool = Function{ defer_loading, description, name, 2 more} | ToolSearch{ type} | ProgrammaticToolCalling{ enabled, type} | 3 more

A credential-free tool available to a reusable agent.

PersistedAgentToolParam = Function{ description, name, parameters, 2 more} | ToolSearch{ type} | ProgrammaticToolCalling{ type, enabled} | 3 more

A tool that can be stored on a reusable agent without session credentials.

PersistedMcpTransport = HTTP{ headers, server_url, type} | Stdio{ args, command, cwd, 2 more}

A credential-free transport used to connect to an MCP server.

PersistedMcpTransportParam = HTTP{ server_url, type, headers} | Stdio{ command, cwd, type, 2 more}

A credential-free transport used to connect to an MCP server.

class SessionError { code, message, param, type }

An error payload with the same public fields as Responses API streaming errors.

class SessionTurnError { code, message }

A customer-safe error describing why a session request failed.

class SetupCommandParam { command, cwd }

A confidential setup command executed before the hosted agent starts.

class Subagent { id, closed_at, instructions, 6 more }

A subagent created within a session.

class SummaryText { text, type }

A reasoning summary content part.

TextFormat = Text{ type} | JSONSchema{ schema, type}

The effective output format for generated text.

TextFormatParam = Text{ type} | JSONSchema{ schema, type}

The output format for generated text.

class TokenUsage { input_tokens, input_tokens_details, output_tokens, 2 more }

Recorded token usage for a session or turn. Usage is best effort and may change.

WebSearchAction = Search{ queries, query, type} | OpenPage{ type, url} | FindInPage{ pattern, type, url} | Other{ type}

An action performed by the web search tool.

BetaAgentsEnvironments

Create an agent environment
beta.agents.environments.create(**kwargs) -> EnvironmentInfo { id, files, object, 4 more }
POST/agents/environments
List agent environments
beta.agents.environments.list(**kwargs) -> CursorPage<EnvironmentInfo { id, files, object, 4 more } >
GET/agents/environments
Retrieve an agent environment
beta.agents.environments.retrieve(environment_id) -> EnvironmentInfo { id, files, object, 4 more }
GET/agents/environments/{environment_id}
ModelsExpand Collapse
class EnvironmentInfo { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

BetaAgentsEnvironmentsFiles

Create an agent environment file
beta.agents.environments.files.create(environment_id, **kwargs) -> EnvironmentFile { environment_id, object, path, size_bytes }
POST/agents/environments/{environment_id}/files
List agent environment files
beta.agents.environments.files.list(environment_id, **kwargs) -> TokenPage<EnvironmentFile { environment_id, object, path, size_bytes } >
GET/agents/environments/{environment_id}/files
ModelsExpand Collapse
class EnvironmentFile { environment_id, object, path, size_bytes }

A live file in an execution environment.

BetaAgentsEnvironmentsTemplates

Create an agent environment template
beta.agents.environments.templates.create(**kwargs) -> EnvironmentTemplate { id, capability_directories, created_at, 9 more }
POST/agents/environments/templates
Delete an agent environment template
beta.agents.environments.templates.delete(environment_template_id) -> EnvironmentTemplateDeleted { id, deleted, object }
DELETE/agents/environments/templates/{environment_template_id}
List agent environment templates
beta.agents.environments.templates.list(**kwargs) -> CursorPage<EnvironmentTemplate { id, capability_directories, created_at, 9 more } >
GET/agents/environments/templates
Retrieve an agent environment template
beta.agents.environments.templates.retrieve(environment_template_id) -> EnvironmentTemplate { id, capability_directories, created_at, 9 more }
GET/agents/environments/templates/{environment_template_id}
Update an agent environment template
beta.agents.environments.templates.update(environment_template_id, **kwargs) -> EnvironmentTemplate { id, capability_directories, created_at, 9 more }
POST/agents/environments/templates/{environment_template_id}
ModelsExpand Collapse
class EnvironmentTemplate { id, capability_directories, created_at, 9 more }

Reusable configuration that provisions a fresh OpenAI-hosted environment for each session.

class EnvironmentTemplateDeleted { id, deleted, object }

A deleted reusable environment template.

BetaAgentsSessions

Create an agent session
beta.agents.sessions.create(**kwargs) -> AgentSession { id, agent, created_at, 10 more }
POST/agents/sessions
Delete an agent session
beta.agents.sessions.delete(session_id) -> AgentSessionDeleted { id, deleted, object }
DELETE/agents/sessions/{session_id}
List agent sessions
beta.agents.sessions.list(**kwargs) -> CursorPage<AgentSession { id, agent, created_at, 10 more } >
GET/agents/sessions
Retrieve an agent session
beta.agents.sessions.retrieve(session_id) -> AgentSession { id, agent, created_at, 10 more }
GET/agents/sessions/{session_id}
Update an agent session
beta.agents.sessions.update(session_id, **kwargs) -> AgentSession { id, agent, created_at, 10 more }
POST/agents/sessions/{session_id}

BetaAgentsSessionsArtifacts

Retrieve agent session artifact content
beta.agents.sessions.artifacts.content(artifact_id, **kwargs) -> StringIO
GET/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
beta.agents.sessions.artifacts.delete(artifact_id, **kwargs) -> SessionArtifactDeleted { id, deleted, object }
DELETE/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
beta.agents.sessions.artifacts.list(session_id, **kwargs) -> CursorPage<SessionArtifact { id, created_at, environment_id, 5 more } >
GET/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
beta.agents.sessions.artifacts.retrieve(artifact_id, **kwargs) -> SessionArtifact { id, created_at, environment_id, 5 more }
GET/agents/sessions/{session_id}/artifacts/{artifact_id}
ModelsExpand Collapse
class SessionArtifact { id, created_at, environment_id, 5 more }

An immutable file published by a completed hosted session turn.

class SessionArtifactDeleted { id, deleted, object }

Confirmation that an immutable session artifact was deleted.

BetaAgentsSessionsEvents

Create agent session input events
beta.agents.sessions.events.create(session_id, **kwargs) -> void
POST/agents/sessions/{session_id}/events
Stream agent session events
beta.agents.sessions.events.stream(session_id) -> AgentSessionEvent
GET/agents/sessions/{session_id}/events

BetaAgentsSessionsItems

List agent session items
beta.agents.sessions.items.list(session_id, **kwargs) -> CursorPage<AgentSessionItem>
GET/agents/sessions/{session_id}/items

BetaAgentsSessionsSubagents

List session subagents
beta.agents.sessions.subagents.list(session_id, **kwargs) -> CursorPage<Subagent { id, closed_at, instructions, 6 more } >
GET/agents/sessions/{session_id}/subagents
Retrieve a session subagent
beta.agents.sessions.subagents.retrieve(subagent_id, **kwargs) -> Subagent { id, closed_at, instructions, 6 more }
GET/agents/sessions/{session_id}/subagents/{subagent_id}

BetaAgentsSessionsSubagentsItems

List subagent items
beta.agents.sessions.subagents.items.list(subagent_id, **kwargs) -> CursorPage<AgentSessionItem>
GET/agents/sessions/{session_id}/subagents/{subagent_id}/items

BetaAgentsSessionsSubagentsTurns

List subagent turns
beta.agents.sessions.subagents.turns.list(subagent_id, **kwargs) -> CursorPage<Turn { id, agent_id, completed_at, 8 more } >
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
beta.agents.sessions.subagents.turns.retrieve(turn_id, **kwargs) -> Turn { id, agent_id, completed_at, 8 more }
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

BetaAgentsSessionsSubagentsTurnsItems

List subagent turn items
beta.agents.sessions.subagents.turns.items.list(turn_id, **kwargs) -> CursorPage<AgentSessionItem>
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items

BetaAgentsSessionsTraces

List agent session traces
beta.agents.sessions.traces.list(session_id, **kwargs) -> CursorPage<SessionTrace { id, created_at, object, 2 more } >
GET/agents/sessions/{session_id}/traces
ModelsExpand Collapse
class SessionTrace { id, created_at, object, 2 more }

BetaAgentsSessionsTurns

List agent session turns
beta.agents.sessions.turns.list(session_id, **kwargs) -> CursorPage<Turn { id, agent_id, completed_at, 8 more } >
GET/agents/sessions/{session_id}/turns
Retrieve an agent session turn
beta.agents.sessions.turns.retrieve(turn_id, **kwargs) -> Turn { id, agent_id, completed_at, 8 more }
GET/agents/sessions/{session_id}/turns/{turn_id}
ModelsExpand Collapse
class Turn { id, agent_id, completed_at, 8 more }

The canonical public representation of a session turn.

BetaAgentsSessionsTurnsItems

List agent session turn items
beta.agents.sessions.turns.items.list(turn_id, **kwargs) -> ConversationCursorPage<AgentSessionItem>
GET/agents/sessions/{session_id}/turns/{turn_id}/items

BetaAgentsVaults

Create a vault
beta.agents.vaults.create(**kwargs) -> Vault { id, created_at, metadata, 2 more }
POST/vaults
Delete a vault
beta.agents.vaults.delete(vault_id) -> VaultDeleted { id, deleted, object }
DELETE/vaults/{vault_id}
List vaults
beta.agents.vaults.list(**kwargs) -> CursorPage<Vault { id, created_at, metadata, 2 more } >
GET/vaults
Retrieve a vault
beta.agents.vaults.retrieve(vault_id) -> Vault { id, created_at, metadata, 2 more }
GET/vaults/{vault_id}
Update a vault
beta.agents.vaults.update(vault_id, **kwargs) -> Vault { id, created_at, metadata, 2 more }
POST/vaults/{vault_id}
ModelsExpand Collapse
class Vault { id, created_at, metadata, 2 more }

A collection of credentials for MCP servers and OpenAI-hosted environments.

class VaultDeleted { id, deleted, object }

Confirmation that a vault was deleted.

VaultStatus = :active | :archived

Whether a vault or credential is active or archived.

VaultStatusFilter = VaultStatus | Array[VaultStatus]

One or more lifecycle statuses to include when listing vaults or credentials.

BetaAgentsVaultsCredentials

Create a vault credential
beta.agents.vaults.credentials.create(vault_id, **kwargs) -> Credential { id, auth, created_at, 5 more }
POST/vaults/{vault_id}/credentials
Delete a vault credential
beta.agents.vaults.credentials.delete(credential_id, **kwargs) -> CredentialDeleted { id, deleted, object }
DELETE/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
beta.agents.vaults.credentials.list(vault_id, **kwargs) -> CursorPage<Credential { id, auth, created_at, 5 more } >
GET/vaults/{vault_id}/credentials
Retrieve a vault credential
beta.agents.vaults.credentials.retrieve(credential_id, **kwargs) -> Credential { id, auth, created_at, 5 more }
GET/vaults/{vault_id}/credentials/{credential_id}
Update a vault credential
beta.agents.vaults.credentials.update(credential_id, **kwargs) -> Credential { id, auth, created_at, 5 more }
POST/vaults/{vault_id}/credentials/{credential_id}
ModelsExpand Collapse
class Credential { id, auth, created_at, 5 more }

Metadata for a stored credential. Secret values are never returned.

CredentialAuth = McpOauth{ expires_at, mcp_server_url, refresh, type} | StaticBearer{ mcp_server_url, type} | EnvironmentVariable{ networking, secret_name, type}

The authentication configuration of a vault credential, excluding secrets.

CredentialAuthCreateParam = McpOauth{ access_token, mcp_server_url, type, 2 more} | StaticBearer{ token, mcp_server_url, type} | EnvironmentVariable{ networking, secret_name, secret_value, type}

Authentication credentials for an MCP server or an OpenAI-hosted environment.

CredentialAuthRotateParam = McpOauth{ type, access_token, expires_at, refresh} | StaticBearer{ token, type} | EnvironmentVariable{ secret_value, type}

Updates to a vault credential without changing its authentication method or destination configuration.

class CredentialDeleted { id, deleted, object }

Confirmation that a vault credential was deleted.

CredentialNetworking = Unrestricted{ type} | Limited{ allowed_hosts, type}

Destination permissions for an environment-variable credential. These do not grant network access to the environment.

CredentialNetworkingParam = Unrestricted{ type} | Limited{ allowed_hosts, type}

Destination permissions for an environment-variable credential. These do not grant network access to the environment.

McpOauthTokenEndpointAuth = None{ type} | ClientSecretBasic{ type} | ClientSecretPost{ type}

The client authentication method used for OAuth token refresh.

McpOauthTokenEndpointAuthCreateParam = None{ type} | ClientSecretBasic{ client_secret, type} | ClientSecretPost{ client_secret, type}

Client authentication credentials for OAuth token refresh.

McpOauthTokenEndpointAuthRotateParam = ClientSecretBasic{ type, client_secret} | ClientSecretPost{ type, client_secret}

Client-secret updates that preserve the credential’s OAuth authentication method.

BetaAssistants

Build Assistants that can call models and use tools.

Create assistant
Deprecated
beta.assistants.create(**kwargs) -> Assistant { id, created_at, description, 10 more }
POST/assistants
Delete assistant
Deprecated
beta.assistants.delete(assistant_id) -> AssistantDeleted { id, deleted, object }
DELETE/assistants/{assistant_id}
List assistants
Deprecated
beta.assistants.list(**kwargs) -> CursorPage<Assistant { id, created_at, description, 10 more } >
GET/assistants
Retrieve assistant
Deprecated
beta.assistants.retrieve(assistant_id) -> Assistant { id, created_at, description, 10 more }
GET/assistants/{assistant_id}
Modify assistant
Deprecated
beta.assistants.update(assistant_id, **kwargs) -> Assistant { id, created_at, description, 10 more }
POST/assistants/{assistant_id}
ModelsExpand Collapse
class Assistant { id, created_at, description, 10 more }

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

class AssistantDeleted { id, deleted, object }
AssistantStreamEvent = ThreadCreated{ data, event, enabled} | ThreadRunCreated{ data, event} | ThreadRunQueued{ data, event} | 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.

AssistantTool = CodeInterpreterTool { type } | FileSearchTool { type, file_search } | FunctionTool { function, type }
class CodeInterpreterTool { type }
class FileSearchTool { type, file_search }
class FunctionTool { function, type }
MessageStreamEvent = ThreadMessageCreated{ data, event} | ThreadMessageInProgress{ data, event} | ThreadMessageDelta{ data, event} | 2 more

Occurs when a message is created.

RunStepStreamEvent = ThreadRunStepCreated{ data, event} | ThreadRunStepInProgress{ data, event} | ThreadRunStepDelta{ data, event} | 4 more

Occurs when a run step is created.

RunStreamEvent = ThreadRunCreated{ data, event} | ThreadRunQueued{ data, event} | ThreadRunInProgress{ data, event} | 7 more

Occurs when a new run is created.

class ThreadStreamEvent { data, event, enabled }

Occurs when a new thread is created.

BetaChatKit

ModelsExpand Collapse
class ChatKitWorkflow { id, state_variables, tracing, version }

Workflow metadata and state returned for the session.

BetaChatKitSessions

Cancel a ChatKit session
beta.chatkit.sessions.cancel(session_id) -> ChatSession { id, chatkit_configuration, client_secret, 7 more }
POST/chatkit/sessions/{session_id}/cancel
Create a ChatKit session
beta.chatkit.sessions.create(**kwargs) -> ChatSession { id, chatkit_configuration, client_secret, 7 more }
POST/chatkit/sessions

BetaChatKitThreads

Delete a ChatKit thread
beta.chatkit.threads.delete(thread_id) -> ThreadDeleteResponse { id, deleted, object }
DELETE/chatkit/threads/{thread_id}
List ChatKit threads
beta.chatkit.threads.list(**kwargs) -> ConversationCursorPage<ChatKitThread { id, created_at, object, 3 more } >
GET/chatkit/threads
List ChatKit thread items
beta.chatkit.threads.list_items(thread_id, **kwargs) -> ConversationCursorPage<ChatKitThreadUserMessageItem { id, attachments, content, 5 more } | ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more } | ChatKitWidgetItem { id, created_at, object, 3 more } | 3 more>
GET/chatkit/threads/{thread_id}/items
Retrieve a ChatKit thread
beta.chatkit.threads.retrieve(thread_id) -> ChatKitThread { id, created_at, object, 3 more }
GET/chatkit/threads/{thread_id}
ModelsExpand Collapse
class ChatSession { id, chatkit_configuration, client_secret, 7 more }

Represents a ChatKit session and its resolved configuration.

class ChatSessionAutomaticThreadTitling { enabled }

Automatic thread title preferences for the session.

class ChatSessionChatKitConfiguration { automatic_thread_titling, file_upload, history }

ChatKit configuration for the session.

class ChatSessionChatKitConfigurationParam { automatic_thread_titling, file_upload, history }

Optional per-session configuration settings for ChatKit behavior.

class ChatSessionExpiresAfterParam { anchor, seconds }

Controls when the session expires relative to an anchor timestamp.

class ChatSessionFileUpload { enabled, max_file_size, max_files }

Upload permissions and limits applied to the session.

class ChatSessionHistory { enabled, recent_threads }

History retention preferences returned for the session.

class ChatSessionRateLimits { max_requests_per_1_minute }

Active per-minute request limit for the session.

class ChatSessionRateLimitsParam { max_requests_per_1_minute }

Controls request rate limits for the session.

ChatSessionStatus = :active | :expired | :cancelled
class ChatSessionWorkflowParam { id, state_variables, tracing, version }

Workflow reference and overrides applied to the chat session.

class ChatKitAttachment { id, mime_type, name, 2 more }

Attachment metadata included on thread items.

class ChatKitResponseOutputText { annotations, text, type }

Assistant response text accompanied by optional annotations.

class ChatKitThread { id, created_at, object, 3 more }

Represents a ChatKit thread and its current status.

class ChatKitThreadAssistantMessageItem { id, content, created_at, 3 more }

Assistant-authored message within a thread.

class ChatKitThreadItemList { data, first_id, has_more, 2 more }

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

class ChatKitThreadUserMessageItem { id, attachments, content, 5 more }

User-authored messages within a thread.

class ChatKitWidgetItem { id, created_at, object, 3 more }

Thread item that renders a widget payload.

class ThreadDeleteResponse { id, deleted, object }

Confirmation payload returned after deleting a thread.

BetaResponses

Create and manage model responses.

Cancel a response
beta.responses.cancel(response_id, **kwargs) -> BetaResponse { id, access_programs, created_at, 33 more }
POST/responses/{response_id}/cancel
Compact conversation
beta.responses.compact(**kwargs) -> BetaCompactedResponse { id, created_at, object, 2 more }
POST/responses/compact
Create a model response
beta.responses.create(**kwargs) -> BetaResponse { id, access_programs, created_at, 33 more }
POST/responses
Delete a model response
beta.responses.delete(response_id, **kwargs) -> void
DELETE/responses/{response_id}
Get a model response
beta.responses.retrieve(response_id, **kwargs) -> BetaResponse { id, access_programs, created_at, 33 more }
GET/responses/{response_id}
ModelsExpand Collapse
class BetaApplyPatchTool { type, allowed_callers }

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

class BetaCompactedResponse { id, created_at, object, 2 more }
BetaComputerAction = Click{ button, type, x, 2 more} | DoubleClick{ keys, type, x, y_} | Drag{ path, type, keys} | 6 more

A click action.

BetaComputerActionList = Array[BetaComputerAction]

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

class BetaComputerTool { type }

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

class BetaComputerUsePreviewTool { display_height, display_width, environment, type }

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

class BetaContainerAuto { type, file_ids, memory_limit, 2 more }
class BetaContainerNetworkPolicyAllowlist { allowed_domains, type, domain_secrets }
class BetaContainerNetworkPolicyDisabled { type }
class BetaContainerNetworkPolicyDomainSecret { domain, name, value }
class BetaContainerReference { container_id, type }
class BetaCustomTool { name, type, allowed_callers, 4 more }

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

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

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

class BetaFunctionShellTool { type, allowed_callers, environment }

A tool that allows the model to execute shell commands.

class BetaFunctionTool { name, parameters, strict, 6 more }

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

class BetaInlineSkill { description, name, source, type }
class BetaInlineSkillSource { data, media_type, type }

Inline skill payload

class BetaLocalEnvironment { type, skills }
class BetaLocalSkill { description, name, path }
BetaMcpToolCallError = McpProtocolError{ code, message, type} | McpToolExecutionError{ content, type} | HTTPError{ code, message, type}
class BetaNamespaceTool { description, name, tools, type }

Groups function/custom tools under a shared namespace.

class BetaResponse { id, access_programs, created_at, 33 more }
class BetaResponseApplyPatchToolCall { id, call_id, operation, 5 more }

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

class BetaResponseApplyPatchToolCallOutput { id, call_id, status, 5 more }

The output emitted by an apply patch tool call.

class BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent }

Emitted when there is a partial audio response.

class BetaResponseAudioDoneEvent { sequence_number, type, agent }

Emitted when the audio response is complete.

class BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent }

Emitted when there is a partial transcript of audio.

class BetaResponseAudioTranscriptDoneEvent { sequence_number, type, agent }

Emitted when the full audio transcript is completed.

class BetaResponseCodeInterpreterCallCodeDeltaEvent { delta, item_id, output_index, 3 more }

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

class BetaResponseCodeInterpreterCallCodeDoneEvent { code, item_id, output_index, 3 more }

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

class BetaResponseCodeInterpreterCallCompletedEvent { item_id, output_index, sequence_number, 2 more }

Emitted when the code interpreter call is completed.

class BetaResponseCodeInterpreterCallInProgressEvent { item_id, output_index, sequence_number, 2 more }

Emitted when a code interpreter call is in progress.

class BetaResponseCodeInterpreterCallInterpretingEvent { item_id, output_index, sequence_number, 2 more }

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

class BetaResponseCodeInterpreterToolCall { id, code, container_id, 4 more }

A tool call to run code.

class BetaResponseCompactionCompactingEvent { item_id, output_index, sequence_number, 2 more }

Emitted when new summary content is sampled for a compaction trigger. Contains no summary content.

class BetaResponseCompactionItem { id, encrypted_content, type, 2 more }

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

class BetaResponseCompactionItemParam { encrypted_content, type, id, agent }

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

class BetaResponseCompletedEvent { response, sequence_number, type, agent }

Emitted when the model response is complete.

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

class BetaResponseComputerToolCallOutputItem { id, call_id, output, 5 more }
class BetaResponseComputerToolCallOutputScreenshot { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

class BetaResponseConfigurationUpdateItem { id, type, agent, reasoning }

A configuration update that applies to subsequent responses until it is replaced by another configuration update.

class BetaResponseConfigurationUpdateItemParam { type, id, agent, reasoning }

An update to the conversation’s response configuration. The configuration remains in effect for subsequent responses until it is replaced by another configuration update.

class BetaResponseContainerReference { container_id, type }

Represents a container created with /v1/containers.

BetaResponseContent = BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseInputImage { detail, type, file_id, 2 more } | BetaResponseInputFile { type, detail, file_data, 4 more } | 3 more

Multi-modal input and output contents.

class BetaResponseContentPartAddedEvent { content_index, item_id, output_index, 4 more }

Emitted when a new content part is added.

class BetaResponseContentPartDoneEvent { content_index, item_id, output_index, 4 more }

Emitted when a content part is done.

class BetaResponseConversationParam { id }

The conversation that this response belongs to.

class BetaResponseCreatedEvent { response, sequence_number, type, agent }

An event that is emitted when a response is created.

class BetaResponseCustomToolCall { call_id, input, name, 6 more }

A call to a custom tool created by the model.

class BetaResponseCustomToolCallInputDeltaEvent { delta, item_id, output_index, 3 more }

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

class BetaResponseCustomToolCallInputDoneEvent { input, item_id, output_index, 3 more }

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

class BetaResponseCustomToolCallItem { id, status, created_by }

A call to a custom tool created by the model.

class BetaResponseCustomToolCallOutput { call_id, output, type, 3 more }

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

class BetaResponseCustomToolCallOutputItem { id, status, created_by }

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

class BetaResponseError { code, message, misalignment }

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

class BetaResponseErrorEvent { code, message, param, 3 more }

Emitted when an error occurs.

class BetaResponseFailedEvent { response, sequence_number, type, agent }

An event that is emitted when a response fails.

class BetaResponseFileSearchCallCompletedEvent { item_id, output_index, sequence_number, 2 more }

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

class BetaResponseFileSearchCallInProgressEvent { item_id, output_index, sequence_number, 2 more }

Emitted when a file search call is initiated.

class BetaResponseFileSearchCallSearchingEvent { item_id, output_index, sequence_number, 2 more }

Emitted when a file search is currently searching.

class BetaResponseFileSearchToolCall { id, queries, status, 3 more }

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

BetaResponseFormatTextConfig = Text{ type} | BetaResponseFormatTextJSONSchemaConfig { name, schema, type, 2 more } | JSONObject{ 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.

class BetaResponseFormatTextJSONSchemaConfig { name, schema, type, 2 more }

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

class BetaResponseFunctionCallArgumentsDeltaEvent { delta, item_id, output_index, 3 more }

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

class BetaResponseFunctionCallArgumentsDoneEvent { arguments, item_id, output_index, 3 more }

Emitted when function-call arguments are finalized.

BetaResponseFunctionCallOutputItem = BetaResponseInputTextContent { text, type, prompt_cache_breakpoint } | BetaResponseInputImageContent { type, detail, file_id, 2 more } | BetaResponseInputFileContent { type, detail, file_data, 4 more }

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

BetaResponseFunctionCallOutputItemList = Array[BetaResponseFunctionCallOutputItem]

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

class BetaResponseFunctionShellCallOutputContent { outcome, stderr, stdout }

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

class BetaResponseFunctionShellToolCall { id, action, call_id, 6 more }

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

class BetaResponseFunctionShellToolCallOutput { id, call_id, max_output_length, 6 more }

The output of a shell tool call that was emitted.

class BetaResponseFunctionToolCall { arguments, call_id, name, 7 more }

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

class BetaResponseFunctionToolCallItem { id, status, created_by }

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

class BetaResponseFunctionToolCallOutputItem { id, output, status, 7 more }
class BetaResponseImageGenCallCompletedEvent { item_id, output_index, sequence_number, 2 more }

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

class BetaResponseImageGenCallGeneratingEvent { item_id, output_index, sequence_number, 2 more }

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

class BetaResponseImageGenCallInProgressEvent { item_id, output_index, sequence_number, 2 more }

Emitted when an image generation tool call is in progress.

class BetaResponseImageGenCallPartialImageEvent { item_id, output_index, partial_image_b64, 8 more }

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

class BetaResponseInProgressEvent { response, sequence_number, type, agent }

Emitted when the response is in progress.

BetaResponseIncludable = :"file_search_call.results" | :"web_search_call.results" | :"web_search_call.action.sources" | 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).
class BetaResponseIncompleteEvent { response, sequence_number, type, agent }

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

Over WebSocket, steering can finish a response with response.incomplete_details.reason set to steered, followed automatically by a successor response.created that commits the queued steering input.

class BetaResponseInjectCreatedEvent { response_id, sequence_number, type, stream_id }

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

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

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

BetaResponseInput = Array[BetaResponseInputItem]

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

class BetaResponseInputAudio { input_audio, type }

An audio input to the model.

BetaResponseInputContent = BetaResponseInputText { text, type, prompt_cache_breakpoint } | BetaResponseInputImage { detail, type, file_id, 2 more } | BetaResponseInputFile { type, detail, file_data, 4 more }

A text input to the model.

class BetaResponseInputFile { type, detail, file_data, 4 more }

A file input to the model.

class BetaResponseInputFileContent { type, detail, file_data, 4 more }

A file input to the model.

class BetaResponseInputImage { detail, type, file_id, 2 more }

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

class BetaResponseInputImageContent { type, detail, file_id, 2 more }

An image input to the model. Learn about image inputs

BetaResponseInputItem = BetaEasyInputMessage { content, role, phase, type } | Message{ content, role, agent, 2 more} | BetaResponseOutputMessage { id, content, role, 4 more } | 33 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.

BetaResponseInputMessageContentList = Array[BetaResponseInputContent]

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

class BetaResponseInputMessageItem { id, content, role, 3 more }
class BetaResponseInputText { text, type, prompt_cache_breakpoint }

A text input to the model.

class BetaResponseInputTextContent { text, type, prompt_cache_breakpoint }

A text input to the model.

BetaResponseItem = BetaResponseInputMessageItem { id, content, role, 3 more } | BetaResponseOutputMessage { id, content, role, 4 more } | BetaResponseFileSearchToolCall { id, queries, status, 3 more } | 30 more

Content item used to generate a response.

class BetaResponseLocalEnvironment { type }

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

class BetaResponseMcpCallArgumentsDeltaEvent { delta, item_id, output_index, 3 more }

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

class BetaResponseMcpCallArgumentsDoneEvent { arguments, item_id, output_index, 3 more }

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

class BetaResponseMcpCallCompletedEvent { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call has completed successfully.

class BetaResponseMcpCallFailedEvent { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call has failed.

class BetaResponseMcpCallInProgressEvent { item_id, output_index, sequence_number, 2 more }

Emitted when an MCP tool call is in progress.

class BetaResponseMcpListToolsCompletedEvent { item_id, output_index, sequence_number, 2 more }

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

class BetaResponseMcpListToolsFailedEvent { item_id, output_index, sequence_number, 2 more }

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

class BetaResponseMcpListToolsInProgressEvent { item_id, output_index, sequence_number, 2 more }

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

class BetaResponseOutputAudio { data, transcript, type }

An audio output from the model.

BetaResponseOutputItem = BetaResponseOutputMessage { id, content, role, 4 more } | BetaResponseFileSearchToolCall { id, queries, status, 3 more } | BetaResponseFunctionToolCall { arguments, call_id, name, 7 more } | 28 more

An output message from the model.

class BetaResponseOutputItemAddedEvent { item, output_index, sequence_number, 2 more }

Emitted when a new output item is added.

class BetaResponseOutputItemDoneEvent { item, output_index, sequence_number, 2 more }

Emitted when an output item is marked done.

class BetaResponseOutputMessage { id, content, role, 4 more }

An output message from the model.

class BetaResponseOutputRefusal { refusal, type }

A refusal from the model.

class BetaResponseOutputText { annotations, text, type, logprobs }

A text output from the model.

class BetaResponseOutputTextAnnotationAddedEvent { annotation, annotation_index, content_index, 5 more }

Emitted when an annotation is added to output text content.

class BetaResponsePrompt { id, variables, version }

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

class BetaResponseQueuedEvent { response, sequence_number, type, agent }

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

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

class BetaResponseReasoningSummaryPartAddedEvent { item_id, output_index, part, 4 more }

Emitted when a new reasoning summary part is added.

class BetaResponseReasoningSummaryPartDoneEvent { item_id, output_index, part, 5 more }

Emitted when a reasoning summary part is completed.

class BetaResponseReasoningSummaryTextDeltaEvent { delta, item_id, output_index, 4 more }

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

class BetaResponseReasoningSummaryTextDoneEvent { item_id, output_index, sequence_number, 4 more }

Emitted when a reasoning summary text is completed.

class BetaResponseReasoningTextDeltaEvent { content_index, delta, item_id, 4 more }

Emitted when a delta is added to a reasoning text.

class BetaResponseReasoningTextDoneEvent { content_index, item_id, output_index, 4 more }

Emitted when a reasoning text is completed.

class BetaResponseRefusalDeltaEvent { content_index, delta, item_id, 4 more }

Emitted when there is a partial refusal text.

class BetaResponseRefusalDoneEvent { content_index, item_id, output_index, 4 more }

Emitted when refusal text is finalized.

class BetaResponseShellCallCommandAddedEvent { command, command_index, output_index, 3 more }

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

class BetaResponseShellCallCommandDeltaEvent { command_index, delta, output_index, 4 more }

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

class BetaResponseShellCallCommandDoneEvent { command, command_index, output_index, 3 more }

A streaming event that indicated a shell command was completed.

class BetaResponseShellCallOutputContentDeltaEvent { command_index, delta, item_id, 4 more }

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

class BetaResponseShellCallOutputContentDoneEvent { command_index, item_id, output, 4 more }

A streaming event that indicated shell call output was completed.

BetaResponseStatus = :completed | :failed | :in_progress | 3 more

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

class BetaResponseSteerAcceptedEvent { sequence_number, steer, type, stream_id }

Emitted when steering input has been validated and queued. Acceptance means the server owns the input, not that it has been applied. The successor’s response.created event is the commit point. If accepted input cannot be committed, response.steer.failed returns it with the same steering ID.

When the response stops for client-owned tool output or approval, the input remains queued and response.steer.pending is emitted after response.completed. Fill the pending event’s required_input stubs with saved results and send one matching explicit response.create per parent. Do not resend accepted input while it is still queued.

BetaResponseSteerErrorCode = :response_not_found | :invalid_input | :steering_not_supported | 4 more | String

A machine-readable steering error code. Clients should handle unknown values because additional codes may be introduced. Known values include:

  • response_not_found: The target response is not available on this connection.
  • invalid_input: The event or input failed validation.
  • steering_not_supported: The model or response execution mode does not support steering.
  • too_many_pending_steers: Too much steering input is pending for the response.
  • response_already_completed: The response completed and is no longer accepting steering input.
  • response_not_active: The response is no longer accepting steering input.
  • successor_creation_failed: The successor response could not be created.
class BetaResponseSteerEvent { input, previous_response_id, type }

Queues user input to steer a response on this WebSocket connection. Input can contain text, images, and files. Steering is supported only for single-agent responses on models and execution modes that support steering. Responses bound to a conversation or using automatic compaction do not support steering.

A response.steer.accepted event acknowledges that the server owns the queued input, not that it has been applied. The successor’s response.created event is the commit point. Input that cannot be committed is returned in response.steer.failed.

Steering may cause the active response to finish at a safe output boundary with response.incomplete and incomplete_details.reason set to steered, followed automatically by a successor response.created. Normal completion can also be followed by an automatic successor. Automatic successors inherit the previous response’s settings and continue from it with the queued input.

If the response stops for client-owned tool output or approval, accepted steering input remains queued and response.steer.pending is emitted after response.completed. Fill the required_input stubs from that event with saved tool results or approval decisions, and send one explicit response.create per parent with the same previous_response_id and WebSocket lane. Do not rerun tools or resend accepted steering input. The queued input is prepended in submission order to that request’s input, and the explicit request retains its own settings.

This event accepts only type, previous_response_id, and input. Do not send stream_id; the target response determines the WebSocket lane.

class BetaResponseSteerFailedEvent { error, sequence_number, steer, 2 more }

Emitted when steering input is rejected or cannot be committed to a successor response. Returns the original, uncommitted input so the client can carry it into response.create when appropriate. Invalid input must be corrected before retrying.

Failures after acceptance include the same steering ID. Failures before an ID is allocated omit steer.id. A lost connection or missing acknowledgement leaves the outcome unknown; it is not proof that the input was rejected.

BetaResponseSteerInput = String | Array[Message{ content, role, type, 3 more} | FunctionCallOutput{ output, type, id, 6 more}]

Input to queue for a continuation of the response. Uses the same string or input-item shape as response.create.input, with a non-empty array when supplying input items.

Steering accepts only messages with the user role. Each message may contain only type, role, and content, with content as a string or an array of input_text, input_image, and input_file parts. The optional type must be message. Other roles, tool outputs, and item types are not supported for steering.

BetaResponseSteerInputContent = BetaResponseInputTextContent { text, type, prompt_cache_breakpoint } | BetaResponseInputImageContent { type, detail, file_id, 2 more } | BetaResponseInputFileContent { type, detail, file_data, 4 more }

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

class BetaResponseSteerPendingEvent { reason, required_input, sequence_number, 3 more }

Emitted when accepted steering input remains queued after the target response completes. The server still owns the input. Do not resend it. The successor’s response.created event is the commit point.

When reason is waiting_for_required_input, this event follows response.completed while the response waits for the tool results or approval decisions identified by required_input. Copy those stubs, fill their result fields using the ordinary response.create input schemas, and submit one continuation per parent with the same previous_response_id and WebSocket lane. Use saved results without rerunning tools. The queued steering input is prepended in submission order to the continuation’s input. That explicit request retains its own settings.

This notification is emitted at most once per steering submission. Multiple submissions for the same parent can report the same required inputs; they do not each require a separate continuation.

BetaResponseSteerPendingReason = :waiting_for_required_input | String

An extensible enum describing why accepted steering input is still queued. Clients should handle unknown values because additional reasons may be introduced. Known values include:

  • waiting_for_required_input: The response is waiting for the tool results or approval decisions identified by required_input.
BetaResponseSteerRequiredInput = FunctionCallOutput{ call_id, name, type} | CustomToolCallOutput{ call_id, type} | ComputerCallOutput{ call_id, type} | 4 more

An input stub identifying an outstanding client-owned tool result or approval decision. Copy the stub and fill the result fields using the corresponding response.create input schema. Use saved results without rerunning the tool. The server does not supply results, approval decisions, or safety acknowledgements in these stubs.

BetaResponseStreamEvent = BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } | BetaResponseAudioDoneEvent { sequence_number, type, agent } | BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } | 56 more

Event emitted while a response is streamed.

class BetaResponseTextConfig { format_, verbosity }

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

class BetaResponseTextDeltaEvent { content_index, delta, item_id, 5 more }

Emitted when there is an additional text delta.

class BetaResponseTextDoneEvent { content_index, item_id, logprobs, 5 more }

Emitted when text content is finalized.

class BetaResponseToolSearchCall { id, arguments, call_id, 5 more }
class BetaResponseToolSearchOutputItem { id, call_id, execution, 5 more }
class BetaResponseToolSearchOutputItemParam { tools, type, id, 4 more }
class BetaResponseUsage { 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.

class BetaResponseWebSearchCallCompletedEvent { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is completed.

class BetaResponseWebSearchCallInProgressEvent { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is initiated.

class BetaResponseWebSearchCallSearchingEvent { item_id, output_index, sequence_number, 2 more }

Emitted when a web search call is executing.

BetaResponsesClientEvent = ResponseCreate{ type, access_programs, background, 32 more} | BetaResponseSteerEvent { input, previous_response_id, type } | BetaResponseInjectEvent { input, response_id, type }

Client events accepted by the Responses WebSocket server.

BetaResponsesServerEvent = BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } & { stream_id} | BetaResponseAudioDoneEvent { sequence_number, type, agent } & { stream_id} | BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } & { stream_id} | 61 more

Server events emitted by the Responses WebSocket server.

class BetaSkillReference { skill_id, type, version }
BetaTool = BetaFunctionTool { name, parameters, strict, 6 more } | BetaFileSearchTool { type, vector_store_ids, filters, 2 more } | BetaComputerTool { type } | 13 more

A tool that can be used to generate a response.

class BetaToolChoiceAllowed { mode, tools, type }

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

class BetaToolChoiceApplyPatch { type }

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

class BetaToolChoiceCustom { name, type }

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

class BetaToolChoiceFunction { name, type }

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

class BetaToolChoiceMcp { server_label, type, name }

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

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

class BetaToolChoiceShell { type }

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

class BetaToolChoiceTypes { type }

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

class BetaToolSearchOutputNamespaceTool { description, name, tools, type }

Groups function/custom tools under a shared namespace.

class BetaToolSearchTool { type, description, execution, parameters }

Hosted or BYOT tool search configuration for deferred tools.

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

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

Create and manage model responses.

List input items
beta.responses.input_items.list(response_id, **kwargs) -> CursorPage<BetaResponseItem>
GET/responses/{response_id}/input_items
ModelsExpand Collapse
class BetaResponseItemList { data, first_id, has_more, 2 more }

A list of Response items.

BetaResponsesInput Tokens

Create and manage model responses.

Get input token counts
beta.responses.input_tokens.count(**kwargs) -> InputTokenCountResponse { input_tokens, object }
POST/responses/input_tokens
ModelsExpand Collapse
class InputTokenCountResponse { input_tokens, object }

BetaThreads

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 }

BetaThreadsMessages

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.

BetaThreadsRuns

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.

BetaThreadsRunsSteps

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.