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

Agents

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.

id: string

The ID of the deleted agent.

minLength0
deleted: boolean

Whether the agent was deleted. Always true.

object: "agent.deleted" (default: "agent.deleted")

The object type. Always agent.deleted.

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.

One of the following:
"in_progress"

The item is in progress.

"completed"

The item is complete.

"incomplete"

The item stopped before completing.

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.

id: string

The ID of the deleted session.

minLength0
deleted: boolean

Whether the session has been removed from the public API. Always true. Physical cleanup may still be in progress.

object: "agent.session.deleted" (default: "agent.session.deleted")

The object type. Always agent.session.deleted.

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 = AgentSessionInputComputerUseApprovalRequestResult { request_id, response, type } or AgentSessionInputMessage { input, type } or AgentSessionInputCancel { type } or AgentSessionInputToolResult { call_id, success, turn_id, 3 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.

AgentsAutomations

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 }
id: string

The deleted automation ID.

minLength0
deleted: boolean

Always true.

object: "agent.automation.deleted" (default: "agent.automation.deleted")

Always agent.automation.deleted.

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.

AgentsAutomationsInvocations

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 }

AgentsEnvironments

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.

AgentsEnvironmentsFiles

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.

AgentsEnvironmentsTemplates

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.

AgentsSessions

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}

AgentsSessionsArtifacts

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.

AgentsSessionsEvents

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

AgentsSessionsItems

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

AgentsSessionsSubagents

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

AgentsSessionsSubagentsItems

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

AgentsSessionsSubagentsTurns

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}

AgentsSessionsSubagentsTurnsItems

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

AgentsSessionsTraces

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

AgentsSessionsTurns

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.

AgentsSessionsTurnsItems

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

AgentsVaults

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.

id: string

The ID of the deleted vault.

minLength0
deleted: boolean

Whether the resource was deleted. Always true.

object: "vault.deleted" (default: "vault.deleted")

The object type. Always vault.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.

AgentsVaultsCredentials

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.