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
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Beta

BetaAgents

Create an agent
POST
/agents
Delete an agent
DELETE
/agents/{agent_id}
List agents
GET
/agents
Retrieve an agent
GET
/agents/{agent_id}
Update an agent
POST
/agents/{agent_id}
Models
Agent object { id, created_at, instructions, 12 more }

A reusable agent scoped to the caller’s project.

AgentBrowserAuthenticationCancelParam object { action, type }
action: "cancel" (default: "cancel")
type: "browser_authentication" (default: "browser_authentication")
AgentBrowserAuthenticationSubmitParam object { action, fields, type, selected_option }
AgentBrowserOriginAccessParam object { decision, type }
AgentCloseSubagentCallItem object { id, recipient_agent_id, sender_agent_id, 3 more }

A request to close a subagent.

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

A command execution produced by the agent.

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

A plaintext or encrypted content part exchanged between agents.

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

A request to spawn a subagent.

AgentDeleted object { id, deleted, object }

A deleted reusable agent.

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

A function call produced by the agent.

AgentFunctionCallOutput = string or array of InputContent

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

AgentFunctionCallOutputParam = string or array of InputContentParam

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

AgentFunctionCallStatus = "in_progress" or "completed" or "failed" or "incomplete"

The status of a tool call.

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

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

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

A call to a tool on an MCP server.

AgentOutputCommandExecutionOutputDeltaEvent object { delta, event_id, item_id, 5 more }

Emitted when command execution produces an output delta.

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

An output item produced by an agent.

AgentOutputItemStatus = "in_progress" or "completed" or "incomplete"

The status of an agent output item.

AgentReasoning object { effort, summary }

The reasoning configuration used by an agent.

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

A reasoning item produced by the agent.

AgentReasoningParam object { effort, summary }

Reasoning configuration for the agent.

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

A request to resume a subagent.

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

A request to send input to another agent.

AgentSession object { id, agent, created_at, 11 more }

A Managed Agents session.

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

An assistant message produced by the agent.

AgentSessionCreatedEvent object { event_id, session, type, obfuscation }

Emitted when a session is created.

AgentSessionDeleted object { id, deleted, object }

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

AgentSessionEnvironmentConnectedEvent object { environment, event_id, session_id, 3 more }

Emitted when a session environment connects.

AgentSessionEnvironmentDisconnectedEvent object { environment, event_id, session_id, 3 more }

Emitted when a session environment disconnects.

AgentSessionEnvironmentExpiredEvent object { environment, event_id, session_id, 3 more }

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

AgentSessionEnvironmentFailedEvent object { environment, event_id, session_id, 3 more }

Emitted when a session environment fails.

AgentSessionEnvironmentPendingEvent object { environment, event_id, session_id, 3 more }

Emitted while a session environment is being prepared.

AgentSessionEnvironmentReadyEvent object { environment, event_id, session_id, 3 more }

Emitted when a hosted session environment is ready to connect.

AgentSessionEnvironmentResetEvent object { environment_id, event_id, reset_count, 4 more }

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

AgentSessionEnvironmentState object { id, error, status, type }

The current state of a session environment.

AgentSessionEnvironmentSuspendedEvent object { environment, event_id, session_id, 3 more }

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

AgentSessionErrorEvent object { error, event_id, session_id, 2 more }

Emitted when a turn or session fails.

AgentSessionEvent = AgentSessionErrorEvent { error, event_id, session_id, 2 more } or AgentSessionEnvironmentReadyEvent { environment, event_id, session_id, 3 more } or AgentSessionEnvironmentSuspendedEvent { environment, event_id, session_id, 3 more } or 30 more

An event emitted by a Managed Agents session.

AgentSessionFailedEvent object { event_id, session, type, obfuscation }

Emitted when a session fails.

AgentSessionIdleEvent object { event_id, session, type, obfuscation }

Emitted when a session becomes idle.

AgentSessionInProgressEvent object { event_id, session, type, obfuscation }

Emitted when a session starts processing a turn.

AgentSessionInputMessageParam object { content, role, type }

A user message submitted to a session.

AgentSessionInputParam = AgentSessionInputMcpApprovalRequestResult { request_id, response, type } or AgentSessionInputComputerUseApprovalRequestResult { request_id, response, type } or AgentSessionInputMessage { input, type } or 2 more

Input submitted to an existing session.

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

An item associated with a session turn.

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

A user or assistant message recorded in a session.

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

A content part in a session message.

AgentSessionRequiresActionEvent object { event_id, session, type, obfuscation }

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

AgentSessionSubagentActiveEvent object { event_id, subagent, type, obfuscation }

Emitted when a closed subagent successfully resumes.

AgentSessionSubagentClosedEvent object { event_id, subagent, type, obfuscation }

Emitted when a subagent is closed.

AgentSessionSubagentCreatedEvent object { event_id, subagent, type, obfuscation }

Emitted when a subagent is created.

AgentSessionTurnCancelledEvent object { event_id, session_id, turn, 4 more }

Emitted when a turn is cancelled.

AgentSessionTurnCompletedEvent object { event_id, session_id, turn, 4 more }

Emitted when a turn completes.

AgentSessionTurnContentPartAddedEvent object { content_index, event_id, item_id, 6 more }

Emitted when an output text content part is added.

AgentSessionTurnContentPartDoneEvent object { content_index, event_id, item_id, 6 more }

Emitted when an output content part is complete.

AgentSessionTurnCreatedEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn is created.

AgentSessionTurnFailedEvent object { event_id, session_id, turn, 4 more }

Emitted when a turn fails.

AgentSessionTurnInProgressEvent object { event_id, session_id, turn, 3 more }

Emitted when a turn starts running.

AgentSessionTurnItemAddedEvent object { event_id, item, output_index, 4 more }

Emitted when an item is added to a turn.

AgentSessionTurnItemDoneEvent object { event_id, item, output_index, 4 more }

Emitted when an output item is complete.

AgentSessionTurnOutputTextDeltaEvent object { content_index, delta, event_id, 6 more }

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

AgentSessionTurnOutputTextDoneEvent object { content_index, event_id, item_id, 6 more }

Emitted when an output text content part is complete.

AgentSessionTurnReasoningSummaryPartAddedEvent object { event_id, item_id, output_index, 6 more }

Emitted when a reasoning summary content part is added.

AgentSessionTurnReasoningSummaryPartDoneEvent object { event_id, item_id, output_index, 7 more }

Emitted when a reasoning summary part is complete.

AgentSessionTurnReasoningSummaryTextDeltaEvent object { delta, event_id, item_id, 6 more }

Emitted when text is appended to a reasoning summary.

AgentSessionTurnReasoningSummaryTextDoneEvent object { event_id, item_id, output_index, 6 more }

Emitted when a reasoning summary content part is complete.

AgentText object { format, verbosity }

The text configuration used by an agent.

AgentTextParam object { format, verbosity }

Configuration for text generated by the agent.

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

A tool available to the agent.

AgentToolParam = Function { description, name, parameters, 3 more } or ToolSearch { type } or ProgrammaticToolCalling { type, enabled } or 4 more

A tool available to the agent.

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

A request to wait for one or more subagents.

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

A web search call produced by the agent.

Environment = None { type } or OpenAIHosted { id, capability_directories, desktop, 7 more } or SelfHosted { id, capability_directories, remote_url, 2 more }

The execution environment for a session.

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

The execution environment and optional reusable template for a session.

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

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

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

A file copied from the OpenAI Files API.

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

A file materialized in an OpenAI-hosted execution environment.

HostedPlugin object { description, name, type }

A plugin installed from an inline ZIP archive.

HostedPluginParam object { description, name, source, type }

Supplies a plugin ZIP directly in the session request.

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

A skill installed in an OpenAI-hosted environment.

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

A skill installed in an OpenAI-hosted environment.

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

A skill installed from the Skills API.

InlineCapabilitySourceParam object { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

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

User-provided content recorded in a session item.

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

Content included in an input message.

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

The transport used to connect to an MCP server.

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

The transport used to connect to an MCP server.

MultiAgentConfig object { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled. Defaults to false.

max_concurrent_subagents: integer or null

Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.

formatint64
minimum1
maximum4294967295
MultiAgentConfigParam object { enabled, max_concurrent_subagents }

Explicit configuration for creating and coordinating subagents.

enabled: boolean

Whether subagent tools are enabled.

max_concurrent_subagents: optional integer

Maximum number of subagents that may run concurrently. Defaults to 6.

formatint64
minimum1
maximum4294967295
OutputText object { text, type }

A text content part produced by the agent.

text: string

The text produced by the agent.

minLength0
type: "output_text" (default: "output_text")

The content type. Always output_text.

PersistedAgentTool = Function { defer_loading, description, name, 3 more } or ToolSearch { type } or ProgrammaticToolCalling { enabled, type } or 4 more

A credential-free tool available to a reusable agent.

PersistedAgentToolParam = Function { description, name, parameters, 3 more } or ToolSearch { type } or ProgrammaticToolCalling { type, enabled } or 4 more

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

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

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

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

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

SessionError object { code, message, param, type }

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

SessionTurnError object { code, message }

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

SetupCommandParam object { command, cwd }

A confidential setup command executed before the hosted agent starts.

command: string

The shell command to execute.

minLength0
maxLength65536
cwd: optional string or null

The absolute working directory. Defaults to /workspace.

minLength0
maxLength4096
Subagent object { id, closed_at, instructions, 6 more }

A subagent created within a session.

SummaryText object { text, type }

A reasoning summary content part.

text: string

The reasoning summary text.

minLength0
type: "summary_text" (default: "summary_text")

The content type. Always summary_text.

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

The effective output format for generated text.

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

The output format for generated text.

TokenUsage object { 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 } or OpenPage { type, url } or FindInPage { pattern, type, url } or Other { type }

An action performed by the web search tool.

BetaAgentsAutomations

Create an automation
POST
/agents/automations
Delete an automation
DELETE
/agents/automations/{automation_id}
List automations
GET
/agents/automations
Pause an automation
POST
/agents/automations/{automation_id}/pause
Resume an automation
POST
/agents/automations/{automation_id}/resume
Get an automation
GET
/agents/automations/{automation_id}
Update an automation
POST
/agents/automations/{automation_id}
Models
Automation = PeriodicAutomation { id, created_at, created_by, 8 more } or OneTimeAutomation { id, created_at, created_by, 7 more }

A saved automation and its schedule.

AutomationAgentConfig object { instructions, model, multi_agent, 6 more }

Inline agent configuration without a generated session-local identity.

AutomationCreatedBy = Developer { type } or Agent { session_id, tool_call_id, type }

How the automation was created, independently of how an invocation started.

AutomationDeleted object { id, deleted, object }
AutomationEnvironment = None { type } or OpenAIHosted { capability_directories, container_size, desktop, 8 more } or SelfHosted { capability_directories, environment_id, type, workspace_directory }

Environment selection saved before an invocation creates its session.

AutomationScheduleParam = Periodic { expression, name, target, 3 more } or Once { name, run_at, target, 2 more }

Creates an automation without invoking it immediately.

AutomationTarget = NewSession { agent, agent_id, environment, 4 more } or ExistingSession { instructions, session_id, type }

Saved target configuration, excluding confidential request-only values.

AutomationTargetParam = NewSession { environment, input, type, 4 more } or ExistingSession { instructions, session_id, type }

The session an automation invocation targets.

OneTimeAutomation object { id, created_at, created_by, 7 more }

Fields shared by periodic and one-time automations.

PeriodicAutomation object { id, created_at, created_by, 8 more }

Fields shared by periodic and one-time automations.

BetaAgentsAutomationsInvocations

Invoke an automation
POST
/agents/automations/{automation_id}/invocations
List automation invocations
GET
/agents/automations/{automation_id}/invocations
Get an automation invocation
GET
/agents/automations/{automation_id}/invocations/{invocation_id}
Models
AutomationInvocation object { id, automation_id, created_at, 7 more }

One attempted delivery by an automation.

AutomationInvocationSource = Manual { type } or Automation { automation, type }

BetaAgentsEnvironments

Create an agent environment
POST
/agents/environments
List agent environments
GET
/agents/environments
Retrieve an agent environment
GET
/agents/environments/{environment_id}
Models
EnvironmentInfo object { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

BetaAgentsEnvironmentsFiles

Write an agent environment file
POST
/agents/environments/{environment_id}/files
List agent environment files
GET
/agents/environments/{environment_id}/files
Models
EnvironmentFile object { environment_id, object, path, size_bytes }

A live file in an execution environment.

BetaAgentsEnvironmentsTemplates

Create an agent environment template
POST
/agents/environments/templates
Delete an agent environment template
DELETE
/agents/environments/templates/{environment_template_id}
List agent environment templates
GET
/agents/environments/templates
Retrieve an agent environment template
GET
/agents/environments/templates/{environment_template_id}
Update an agent environment template
POST
/agents/environments/templates/{environment_template_id}
Models
EnvironmentTemplate object { id, capability_directories, created_at, 9 more }

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

EnvironmentTemplateDeleted object { id, deleted, object }

A deleted reusable environment template.

BetaAgentsSessions

Create an agent session
POST
/agents/sessions
Delete an agent session
DELETE
/agents/sessions/{session_id}
List agent sessions
GET
/agents/sessions
Retrieve an agent session
GET
/agents/sessions/{session_id}
Update an agent session
POST
/agents/sessions/{session_id}

BetaAgentsSessionsArtifacts

Retrieve agent session artifact content
GET
/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
DELETE
/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
GET
/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
GET
/agents/sessions/{session_id}/artifacts/{artifact_id}
Models
SessionArtifact object { id, created_at, environment_id, 5 more }

An immutable file published by a completed hosted session turn.

SessionArtifactDeleted object { id, deleted, object }

Confirmation that an immutable session artifact was deleted.

BetaAgentsSessionsEvents

Create agent session input events
POST
/agents/sessions/{session_id}/events
Stream agent session events
GET
/agents/sessions/{session_id}/events

BetaAgentsSessionsItems

List agent session items
GET
/agents/sessions/{session_id}/items

BetaAgentsSessionsSubagents

List session subagents
GET
/agents/sessions/{session_id}/subagents
Retrieve a session subagent
GET
/agents/sessions/{session_id}/subagents/{subagent_id}

BetaAgentsSessionsSubagentsItems

List subagent items
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/items

BetaAgentsSessionsSubagentsTurns

List subagent turns
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

BetaAgentsSessionsSubagentsTurnsItems

List subagent turn items
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items

BetaAgentsSessionsTraces

List agent session traces
GET
/agents/sessions/{session_id}/traces
Models
SessionTrace object { id, created_at, object, 2 more }

BetaAgentsSessionsTurns

List agent session turns
GET
/agents/sessions/{session_id}/turns
Retrieve an agent session turn
GET
/agents/sessions/{session_id}/turns/{turn_id}
Models
Turn object { id, agent_id, completed_at, 9 more }

The canonical public representation of a session turn.

BetaAgentsSessionsTurnsItems

List agent session turn items
GET
/agents/sessions/{session_id}/turns/{turn_id}/items

BetaAgentsVaults

Create a vault
POST
/vaults
Delete a vault
DELETE
/vaults/{vault_id}
List vaults
GET
/vaults
Retrieve a vault
GET
/vaults/{vault_id}
Update a vault
POST
/vaults/{vault_id}
Models
Vault object { id, created_at, metadata, 2 more }

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

VaultDeleted object { id, deleted, object }

Confirmation that a vault was deleted.

VaultStatus = "active" or "archived"

Whether a vault or credential is active or archived.

One of the following:
"active"
"archived"
VaultStatusFilter = VaultStatus or array of VaultStatus

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

BetaAgentsVaultsCredentials

Create a vault credential
POST
/vaults/{vault_id}/credentials
Delete a vault credential
DELETE
/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
GET
/vaults/{vault_id}/credentials
Retrieve a vault credential
GET
/vaults/{vault_id}/credentials/{credential_id}
Update a vault credential
POST
/vaults/{vault_id}/credentials/{credential_id}
Models
Credential object { 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 } or StaticBearer { mcp_server_url, type } or EnvironmentVariable { networking, secret_name, type }

The authentication configuration of a vault credential, excluding secrets.

CredentialAuthCreateParam = McpOauth { access_token, mcp_server_url, type, 2 more } or StaticBearer { token, mcp_server_url, type } or 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 } or StaticBearer { token, type } or EnvironmentVariable { secret_value, type }

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

CredentialDeleted object { id, deleted, object }

Confirmation that a vault credential was deleted.

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

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

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

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

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

The client authentication method used for OAuth token refresh.

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

Client authentication credentials for OAuth token refresh.

McpOauthTokenEndpointAuthRotateParam = ClientSecretBasic { type, client_secret } or 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
POST
/assistants
Delete assistant
Deprecated
DELETE
/assistants/{assistant_id}
List assistants
Deprecated
GET
/assistants
Retrieve assistant
Deprecated
GET
/assistants/{assistant_id}
Modify assistant
Deprecated
POST
/assistants/{assistant_id}
Models
Assistant object { id, created_at, description, 10 more }

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

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

CodeInterpreterTool object { type }
type: "code_interpreter"

The type of tool being defined: code_interpreter

FileSearchTool object { type, file_search }
FunctionTool object { function, type }
function: FunctionDefinition { name, description, parameters, strict }
type: "function"

The type of tool being defined: function

MessageStreamEvent = ThreadMessageCreated { data, event } or ThreadMessageInProgress { data, event } or ThreadMessageDelta { data, event } or 2 more

Occurs when a message is created.

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

Occurs when a run step is created.

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

Occurs when a new run is created.

ThreadStreamEvent object { data, event, enabled }

Occurs when a new thread is created.

BetaChatKit

Models
ChatKitWorkflow object { id, state_variables, tracing, version }

Workflow metadata and state returned for the session.

BetaChatKitSessions

Cancel a ChatKit session
POST
/chatkit/sessions/{session_id}/cancel
Create a ChatKit session
POST
/chatkit/sessions

BetaChatKitThreads

Delete a ChatKit thread
DELETE
/chatkit/threads/{thread_id}
List ChatKit threads
GET
/chatkit/threads
List ChatKit thread items
GET
/chatkit/threads/{thread_id}/items
Retrieve a ChatKit thread
GET
/chatkit/threads/{thread_id}
Models
ChatSession object { id, chatkit_configuration, client_secret, 7 more }

Represents a ChatKit session and its resolved configuration.

ChatSessionAutomaticThreadTitling object { enabled }

Automatic thread title preferences for the session.

enabled: boolean

Whether automatic thread titling is enabled.

ChatSessionChatKitConfiguration object { automatic_thread_titling, file_upload, history }

ChatKit configuration for the session.

ChatSessionChatKitConfigurationParam object { automatic_thread_titling, file_upload, history }

Optional per-session configuration settings for ChatKit behavior.

ChatSessionExpiresAfterParam object { anchor, seconds }

Controls when the session expires relative to an anchor timestamp.

anchor: "created_at" (default: "created_at")

Base timestamp used to calculate expiration. Currently fixed to created_at.

seconds: integer

Number of seconds after the anchor when the session expires.

formatint64
minimum1
maximum600
ChatSessionFileUpload object { enabled, max_file_size, max_files }

Upload permissions and limits applied to the session.

ChatSessionHistory object { enabled, recent_threads }

History retention preferences returned for the session.

enabled: boolean

Indicates if chat history is persisted for the session.

recent_threads: integer or null

Number of prior threads surfaced in history views. Defaults to null when all history is retained.

ChatSessionRateLimits object { max_requests_per_1_minute }

Active per-minute request limit for the session.

max_requests_per_1_minute: integer

Maximum allowed requests per one-minute window.

ChatSessionRateLimitsParam object { max_requests_per_1_minute }

Controls request rate limits for the session.

max_requests_per_1_minute: optional integer

Maximum number of requests allowed per minute for the session. Defaults to 10.

minimum1
ChatSessionStatus = "active" or "expired" or "cancelled"
ChatSessionWorkflowParam object { id, state_variables, tracing, version }

Workflow reference and overrides applied to the chat session.

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

Attachment metadata included on thread items.

ChatKitResponseOutputText object { annotations, text, type }

Assistant response text accompanied by optional annotations.

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

Represents a ChatKit thread and its current status.

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

Assistant-authored message within a thread.

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

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

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

User-authored messages within a thread.

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

Thread item that renders a widget payload.

ThreadDeleteResponse object { id, deleted, object }

Confirmation payload returned after deleting a thread.

BetaResponses

Create and manage model responses.

Cancel a response
POST
/responses/{response_id}/cancel
Compact conversation
POST
/responses/compact
Connect
WebSocket
/responses
Create a model response
POST
/responses
Delete a model response
DELETE
/responses/{response_id}
Get a model response
GET
/responses/{response_id}
Models
BetaCompactedResponse object { id, created_at, object, 3 more }
BetaComputerAction = Click { button, type, x, 2 more } or DoubleClick { keys, type, x, y } or Drag { path, type, keys } or 6 more

A click action.

BetaComputerActionList = array of BetaComputerAction

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

BetaContainerAuto object { type, file_ids, memory_limit, 2 more }
BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }
BetaContainerNetworkPolicyDisabled object { type }
type: "disabled" (default: "disabled")

Disable outbound network access. Always disabled.

BetaContainerNetworkPolicyDomainSecret object { domain, name, value }
BetaContainerReference object { container_id, type }
container_id: string

The ID of the referenced container.

type: "container_reference" (default: "container_reference")

References a container created with the /v1/containers endpoint

BetaEasyInputMessage object { content, role, phase, type }

A message input to the model with a role indicating instruction following hierarchy. Instructions given with the developer or system role take precedence over instructions given with the user role. Messages with the assistant role are presumed to have been generated by the model in previous interactions.

BetaImageDetail = "low" or "high" or "auto" or "original"
BetaInlineSkill object { description, name, source, type }
BetaInlineSkillSource object { data, media_type, type }

Inline skill payload

BetaLocalEnvironment object { type, skills }
BetaLocalSkill object { description, name, path }
BetaMcpToolCallError = McpProtocolError { code, message, type } or McpToolExecutionError { content, type } or HTTPError { code, message, type }
BetaResponse object { id, access_programs, created_at, 37 more }
BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }

Emitted when there is a partial audio response.

BetaResponseAudioDoneEvent object { sequence_number, type, agent }

Emitted when the audio response is complete.

BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }

Emitted when there is a partial transcript of audio.

BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }

Emitted when the full audio transcript is completed.

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

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

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

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

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

Emitted when the code interpreter call is completed.

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

Emitted when a code interpreter call is in progress.

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

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

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

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

BetaResponseCompletedEvent object { response, sequence_number, type, agent }

Emitted when the model response is complete.

BetaResponseComputerToolCallOutputScreenshot object { type, file_id, image_url }

A computer screenshot image used with the computer use tool.

BetaResponseContainerReference object { container_id, type }

Represents a container created with /v1/containers.

container_id: string
type: "container_reference" (default: "container_reference")

The environment type. Always container_reference.

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

Multi-modal input and output contents.

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

Emitted when a new content part is added.

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

Emitted when a content part is done.

BetaResponseConversationParam object { id }

The conversation that this response belongs to.

id: string

The unique ID of the conversation.

BetaResponseCreatedEvent object { response, sequence_number, type, agent }

An event that is emitted when a response is created.

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

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

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

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

BetaResponseDeleteResponse object { id, deleted, object }
BetaResponseError object { code, message, misalignment, 2 more }

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

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

Emitted when an error occurs.

BetaResponseFailedEvent object { response, sequence_number, type, agent }

An event that is emitted when a response fails.

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

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

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

Emitted when a file search call is initiated.

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

Emitted when a file search is currently searching.

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

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

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

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

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

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

Emitted when function-call arguments are finalized.

BetaResponseFunctionShellCallOutputContent object { outcome, stderr, stdout }

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

BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }

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

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

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

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

Emitted when an image generation tool call is in progress.

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

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

BetaResponseInProgressEvent object { response, sequence_number, type, agent }

Emitted when the response is in progress.

BetaResponseIncludable = "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more

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

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

BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }

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

BetaResponseInjectEvent object { input, response_id, type }

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

BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }

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

BetaResponseInputAudio object { input_audio, type }

An audio input to the model.

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

A text input to the model.

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

A file input to the model.

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

A file input to the model.

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

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

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

An image input to the model. Learn about image inputs

BetaResponseInputMessageContentList = array of BetaResponseInputContent

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

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

A text input to the model.

BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }

A text input to the model.

BetaResponseLocalEnvironment object { type }

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

type: "local" (default: "local")

The environment type. Always local.

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

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

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

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

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

Emitted when an MCP tool call has completed successfully.

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

Emitted when an MCP tool call has failed.

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

Emitted when an MCP tool call is in progress.

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

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

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

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

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

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

BetaResponseOutputAudio object { data, transcript, type }

An audio output from the model.

BetaResponseOutputItem = BetaResponseOutputMessage { id, content, role, 4 more } or FileSearchCall { id, queries, status, 3 more } or FunctionCall { arguments, call_id, name, 7 more } or 28 more

An output message from the model.

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

Emitted when a new output item is added.

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

Emitted when an output item is marked done.

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

An output message from the model.

BetaResponseOutputRefusal object { refusal, type }

A refusal from the model.

refusal: string

The refusal explanation from the model.

type: "refusal" (default: "refusal")

The type of the refusal. Always refusal.

BetaResponseOutputText object { annotations, logprobs, text, type }

A text output from the model.

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

Emitted when an annotation is added to output text content.

BetaResponsePrompt object { id, variables, version }

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

BetaResponseQueuedEvent object { response, sequence_number, type, agent }

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

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

Emitted when a new reasoning summary part is added.

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

Emitted when a reasoning summary part is completed.

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

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

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

Emitted when a reasoning summary text is completed.

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

Emitted when a delta is added to a reasoning text.

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

Emitted when a reasoning text is completed.

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

Emitted when there is a partial refusal text.

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

Emitted when refusal text is finalized.

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

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

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

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

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

A streaming event that indicated a shell command was completed.

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

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

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

A streaming event that indicated shell call output was completed.

BetaResponseStatus = "completed" or "failed" or "in_progress" or 3 more

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

BetaResponseSteerAcceptedEvent object { 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" or "invalid_input" or "steering_not_supported" or 4 more or 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.
BetaResponseSteerEvent object { 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.

BetaResponseSteerFailedEvent object { 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 or array of Message { content, role, type, 3 more } or 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.

BetaResponseSteerPendingEvent object { 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" or 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.
One of the following:
"waiting_for_required_input"

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.
string
BetaResponseSteerRequiredInput = FunctionCallOutput { call_id, name, type } or CustomToolCallOutput { call_id, type } or ComputerCallOutput { call_id, type } or 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 } or BetaResponseAudioDoneEvent { sequence_number, type, agent } or BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } or 56 more

Event emitted while a response is streamed.

BetaResponseTextConfig object { format, verbosity }

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

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

Emitted when there is an additional text delta.

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

Emitted when text content is finalized.

BetaResponseUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }

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

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

Emitted when a web search call is completed.

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

Emitted when a web search call is initiated.

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

Emitted when a web search call is executing.

BetaResponsesClientEvent = ResponseCreate { type, access_programs, background, 34 more } or BetaResponseSteerEvent { input, previous_response_id, type } or BetaResponseInjectEvent { input, response_id, type }

Client events accepted by the Responses WebSocket server.

BetaResponsesServerEvent = BetaResponseAudioDeltaEvent { delta, sequence_number, type, agent } or BetaResponseAudioDoneEvent { sequence_number, type, agent } or BetaResponseAudioTranscriptDeltaEvent { delta, sequence_number, type, agent } or 61 more

Server events emitted by the Responses WebSocket server.

BetaServiceTier = "auto" or "default" or "flex" or 4 more

Specifies the processing type used for serving the request.

  • If set to ‘auto’, then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use ‘default’.
  • If set to ‘default’, then the request will be processed with the standard pricing and performance for the selected model.
  • If set to ‘flex’, then the request will be processed with the Flex Processing service tier.
  • To opt-in to Fast mode at the request level, include the service_tier=fast or service_tier=priority parameter for Responses or Chat Completions. The response will show service_tier=priority regardless of if you specify service_tier=fast or priority in your request.
  • If set to ‘ultrafast’, then the request will be processed with the access-controlled Ultrafast Processing service tier. This tier is currently available for gpt-5.6-sol; a response served through it will show service_tier=ultrafast.
  • When not set, the default behavior is ‘auto’.

When the service_tier parameter is set, the response body will include the service_tier value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

BetaSkillReference object { skill_id, type, version }
BetaToolChoiceAllowed object { mode, tools, type }

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

BetaToolChoiceApplyPatch object { type }

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

type: "apply_patch" (default: "apply_patch")

The tool to call. Always apply_patch.

BetaToolChoiceCustom object { name, type }

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

name: string

The name of the custom tool to call.

type: "custom"

For custom tool calling, the type is always custom.

BetaToolChoiceFunction object { name, type }

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

name: string

The name of the function to call.

type: "function"

For function calling, the type is always function.

BetaToolChoiceMcp object { server_label, type, name }

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

BetaToolChoiceOptions = "none" or "auto" or "required"

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

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

auto means the model can pick between generating a message or calling one or more tools.

required means the model must call one or more tools.

BetaToolChoiceShell object { type }

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

type: "shell" (default: "shell")

The tool to call. Always shell.

BetaToolChoiceTypes object { type }

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

BetaToolSearchOutputNamespaceTool object { description, name, tools, type }

Groups function/custom tools under a shared namespace.

BetaResponsesInput Items

Create and manage model responses.

List input items
GET
/responses/{response_id}/input_items
Models
BetaResponseItemList object { data, first_id, has_more, 2 more }

A list of Response items.

BetaResponsesInput Tokens

Create and manage model responses.

Get input token counts
POST
/responses/input_tokens
Models
InputTokenCountResponse object { input_tokens, object }
input_tokens: integer
object: "response.input_tokens" (default: "response.input_tokens")

BetaThreads

Build Assistants that can call models and use tools.

Create thread
Deprecated
POST
/threads
Create thread and run
Deprecated
POST
/threads/runs
Delete thread
Deprecated
DELETE
/threads/{thread_id}
Retrieve thread
Deprecated
GET
/threads/{thread_id}
Modify thread
Deprecated
POST
/threads/{thread_id}
Models
AssistantResponseFormatOption = "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.

AssistantToolChoice object { type, function }

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

AssistantToolChoiceFunction object { name }
name: string

The name of the function to call.

AssistantToolChoiceOption = "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.

ThreadDeleted object { id, deleted, object }

BetaThreadsMessages

Build Assistants that can call models and use tools.

Create message
Deprecated
POST
/threads/{thread_id}/messages
Delete message
Deprecated
DELETE
/threads/{thread_id}/messages/{message_id}
List messages
Deprecated
GET
/threads/{thread_id}/messages
Retrieve message
Deprecated
GET
/threads/{thread_id}/messages/{message_id}
Modify message
Deprecated
POST
/threads/{thread_id}/messages/{message_id}
Models
FileCitationAnnotation 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.

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

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

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

ImageFile object { file_id, detail }
ImageFileContentBlock object { image_file, type }

References an image File in the content of a message.

image_file: ImageFile { file_id, detail }
type: "image_file"

Always image_file.

ImageFileDelta object { detail, file_id }
ImageFileDeltaBlock object { index, type, image_file }

References an image File in the content of a message.

ImageURL object { url, detail }
ImageURLContentBlock object { image_url, type }

References an image URL in the content of a message.

image_url: ImageURL { url, detail }
type: "image_url"

The type of the content part.

ImageURLDelta object { detail, url }
ImageURLDeltaBlock 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.

MessageDeleted object { id, deleted, object }
MessageDelta object { content, role }

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

MessageDeltaEvent object { id, delta, object }

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

RefusalContentBlock object { refusal, type }

The refusal content generated by the assistant.

refusal: string
type: "refusal"

Always refusal.

RefusalDeltaBlock object { index, type, refusal }

The refusal content that is part of a message.

Text object { annotations, value }
TextContentBlock object { text, type }

The text content that is part of a message.

text: Text { annotations, value }
type: "text"

Always text.

TextContentBlockParam object { text, type }

The text content that is part of a message.

text: string

Text content to be sent to the model

type: "text"

Always text.

TextDelta object { annotations, value }
TextDeltaBlock object { index, type, text }

The text content that is part of a message.

BetaThreadsRuns

Build Assistants that can call models and use tools.

Cancel a run
Deprecated
POST
/threads/{thread_id}/runs/{run_id}/cancel
Create run
Deprecated
POST
/threads/{thread_id}/runs
List runs
Deprecated
GET
/threads/{thread_id}/runs
Retrieve run
Deprecated
GET
/threads/{thread_id}/runs/{run_id}
Submit tool outputs to run
Deprecated
POST
/threads/{thread_id}/runs/{run_id}/submit_tool_outputs
Modify run
Deprecated
POST
/threads/{thread_id}/runs/{run_id}
Models
RequiredActionFunctionToolCall object { id, function, type }

Tool call objects

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

Represents an execution run on a thread.

BetaThreadsRunsSteps

Build Assistants that can call models and use tools.

List run steps
Deprecated
GET
/threads/{thread_id}/runs/{run_id}/steps
Retrieve run step
Deprecated
GET
/threads/{thread_id}/runs/{run_id}/steps/{step_id}
Models
CodeInterpreterLogs object { index, type, logs }

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

CodeInterpreterOutputImage object { index, type, image }
CodeInterpreterToolCall object { id, code_interpreter, type }

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

CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }

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

FileSearchToolCall object { id, file_search, type }
FileSearchToolCallDelta object { file_search, index, type, id }
FunctionToolCall object { id, function, type }
FunctionToolCallDelta object { index, type, id, function }
MessageCreationStepDetails object { message_creation, type }

Details of the message creation by the run step.

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

Represents a step in execution of a run.

RunStepDeltaEvent object { id, delta, object }

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

RunStepDeltaMessageDelta object { type, message_creation }

Details of the message creation by the run step.

RunStepInclude = "step_details.tool_calls[*].file_search.results[*].content"
ToolCallDeltaObject object { type, tool_calls }

Details of the tool call.

ToolCallsStepDetails object { tool_calls, type }

Details of the tool call.