Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Agents

Create an agent
beta.agents.create(**kwargs) -> Agent
POST
/agents
Delete an agent
beta.agents.delete(agent_id) -> AgentDeleted
DELETE
/agents/{agent_id}
List agents
beta.agents.list(**kwargs) -> SyncCursorPage[Agent]
GET
/agents
Retrieve an agent
beta.agents.retrieve(agent_id) -> Agent
GET
/agents/{agent_id}
Update an agent
beta.agents.update(agent_id, **kwargs) -> Agent
POST
/agents/{agent_id}
Models
class Agent: …

A reusable agent scoped to the caller’s project.

class AgentBrowserAuthenticationCancelParam: …
class AgentBrowserAuthenticationSubmitParam: …
class AgentBrowserOriginAccessParam: …
class AgentCloseSubagentCallItem: …

A request to close a subagent.

class AgentCommandExecutionItem: …

A command execution produced by the agent.

AgentContent

A plaintext or encrypted content part exchanged between agents.

class AgentCreateSubagentCallItem: …

A request to spawn a subagent.

class AgentDeleted: …

A deleted reusable agent.

class AgentFunctionCallItem: …

A function call produced by the agent.

Union[str, List[InputContent]]

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

Union[str, List[InputContentParam]]

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

Literal["in_progress", "completed", "failed", "incomplete"]

The status of a tool call.

  • in_progress - The call is in progress.
  • completed - The call completed successfully.
  • failed - The call failed.
  • incomplete - The call stopped before completing.
class AgentInterruptSubagentCallItem: …

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

class AgentMcpCallItem: …

A call to a tool on an MCP server.

class AgentOutputCommandExecutionOutputDeltaEvent: …

Emitted when command execution produces an output delta.

AgentOutputItem

An output item produced by an agent.

Literal["in_progress", "completed", "incomplete"]

The status of an agent output item.

  • in_progress - The item is in progress.
  • completed - The item is complete.
  • incomplete - The item stopped before completing.
class AgentReasoning: …

The reasoning configuration used by an agent.

class AgentReasoningItem: …

A reasoning item produced by the agent.

class AgentReasoningParam: …

Reasoning configuration for the agent.

class AgentResumeSubagentCallItem: …

A request to resume a subagent.

class AgentSendSubagentInputCallItem: …

A request to send input to another agent.

class AgentSession: …

A Managed Agents session.

class AgentSessionAssistantMessage: …

An assistant message produced by the agent.

class AgentSessionCreatedEvent: …

Emitted when a session is created.

class AgentSessionDeleted: …

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

class AgentSessionEnvironmentConnectedEvent: …

Emitted when a session environment connects.

class AgentSessionEnvironmentDisconnectedEvent: …

Emitted when a session environment disconnects.

class AgentSessionEnvironmentExpiredEvent: …

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

class AgentSessionEnvironmentFailedEvent: …

Emitted when a session environment fails.

class AgentSessionEnvironmentPendingEvent: …

Emitted while a session environment is being prepared.

class AgentSessionEnvironmentReadyEvent: …

Emitted when a hosted session environment is ready to connect.

class AgentSessionEnvironmentResetEvent: …

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

class AgentSessionEnvironmentState: …

The current state of a session environment.

class AgentSessionEnvironmentSuspendedEvent: …

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

class AgentSessionErrorEvent: …

Emitted when a turn or session fails.

AgentSessionEvent

An event emitted by a Managed Agents session.

class AgentSessionFailedEvent: …

Emitted when a session fails.

class AgentSessionIdleEvent: …

Emitted when a session becomes idle.

class AgentSessionInProgressEvent: …

Emitted when a session starts processing a turn.

class AgentSessionInputMessageParam: …

A user message submitted to a session.

AgentSessionInputParam

Input submitted to an existing session.

AgentSessionItem

An item associated with a session turn.

class AgentSessionMessage: …

A user or assistant message recorded in a session.

AgentSessionMessageContent

A content part in a session message.

class AgentSessionRequiresActionEvent: …

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

class AgentSessionSubagentActiveEvent: …

Emitted when a closed subagent successfully resumes.

class AgentSessionSubagentClosedEvent: …

Emitted when a subagent is closed.

class AgentSessionSubagentCreatedEvent: …

Emitted when a subagent is created.

class AgentSessionTurnCancelledEvent: …

Emitted when a turn is cancelled.

class AgentSessionTurnCompletedEvent: …

Emitted when a turn completes.

class AgentSessionTurnContentPartAddedEvent: …

Emitted when an output text content part is added.

class AgentSessionTurnContentPartDoneEvent: …

Emitted when an output content part is complete.

class AgentSessionTurnCreatedEvent: …

Emitted when a turn is created.

class AgentSessionTurnFailedEvent: …

Emitted when a turn fails.

class AgentSessionTurnInProgressEvent: …

Emitted when a turn starts running.

class AgentSessionTurnItemAddedEvent: …

Emitted when an item is added to a turn.

class AgentSessionTurnItemDoneEvent: …

Emitted when an output item is complete.

class AgentSessionTurnOutputTextDeltaEvent: …

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

class AgentSessionTurnOutputTextDoneEvent: …

Emitted when an output text content part is complete.

class AgentSessionTurnReasoningSummaryPartAddedEvent: …

Emitted when a reasoning summary content part is added.

class AgentSessionTurnReasoningSummaryPartDoneEvent: …

Emitted when a reasoning summary part is complete.

class AgentSessionTurnReasoningSummaryTextDeltaEvent: …

Emitted when text is appended to a reasoning summary.

class AgentSessionTurnReasoningSummaryTextDoneEvent: …

Emitted when a reasoning summary content part is complete.

class AgentText: …

The text configuration used by an agent.

class AgentTextParam: …

Configuration for text generated by the agent.

AgentTool

A tool available to the agent.

AgentToolParam

A tool available to the agent.

class AgentWaitForSubagentsCallItem: …

A request to wait for one or more subagents.

class AgentWebSearchCallItem: …

A web search call produced by the agent.

Environment

The execution environment for a session.

EnvironmentParam

The execution environment and optional reusable template for a session.

HostedEnvironmentFile

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

class HostedEnvironmentFileID: …

A file copied from the OpenAI Files API.

HostedEnvironmentFileParam

A file materialized in an OpenAI-hosted execution environment.

class HostedPlugin: …

A plugin installed from an inline ZIP archive.

class HostedPluginParam: …

Supplies a plugin ZIP directly in the session request.

HostedSkill

A skill installed in an OpenAI-hosted environment.

HostedSkillParam

A skill installed in an OpenAI-hosted environment.

class HostedSkillReference: …

A skill installed from the Skills API.

class InlineCapabilitySourceParam: …

Provides ZIP bytes encoded with standard base64.

InputContent

User-provided content recorded in a session item.

InputContentParam

Content included in an input message.

McpTransport

The transport used to connect to an MCP server.

McpTransportParam

The transport used to connect to an MCP server.

class MultiAgentConfig: …

The resolved configuration for creating and coordinating subagents.

class MultiAgentConfigParam: …

Explicit configuration for creating and coordinating subagents.

class OutputText: …

A text content part produced by the agent.

PersistedAgentTool

A credential-free tool available to a reusable agent.

PersistedAgentToolParam

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

PersistedMcpTransport

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

PersistedMcpTransportParam

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

class SessionError: …

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

class SessionTurnError: …

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

class SetupCommandParam: …

A confidential setup command executed before the hosted agent starts.

class Subagent: …

A subagent created within a session.

class SummaryText: …

A reasoning summary content part.

TextFormat

The effective output format for generated text.

TextFormatParam

The output format for generated text.

class TokenUsage: …

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

WebSearchAction

An action performed by the web search tool.

AgentsAutomations

Create an automation
beta.agents.automations.create(**kwargs) -> Automation
POST
/agents/automations
Delete an automation
beta.agents.automations.delete(automation_id) -> AutomationDeleted
DELETE
/agents/automations/{automation_id}
List automations
beta.agents.automations.list(**kwargs) -> SyncCursorPage[Automation]
GET
/agents/automations
Pause an automation
beta.agents.automations.pause(automation_id) -> Automation
POST
/agents/automations/{automation_id}/pause
Resume an automation
beta.agents.automations.resume(automation_id) -> Automation
POST
/agents/automations/{automation_id}/resume
Get an automation
beta.agents.automations.retrieve(automation_id) -> Automation
GET
/agents/automations/{automation_id}
Update an automation
beta.agents.automations.update(automation_id, **kwargs) -> Automation
POST
/agents/automations/{automation_id}
Models
Automation

A saved automation and its schedule.

class AutomationAgentConfig: …

Inline agent configuration without a generated session-local identity.

AutomationCreatedBy

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

class AutomationDeleted: …
AutomationEnvironment

Environment selection saved before an invocation creates its session.

Dict[str, str]
AutomationTarget

Saved target configuration, excluding confidential request-only values.

AutomationTargetParam

The session an automation invocation targets.

class OneTimeAutomation: …

Fields shared by periodic and one-time automations.

class PeriodicAutomation: …

Fields shared by periodic and one-time automations.

AgentsAutomationsInvocations

Invoke an automation
beta.agents.automations.invocations.create(automation_id) -> AutomationInvocation
POST
/agents/automations/{automation_id}/invocations
List automation invocations
beta.agents.automations.invocations.list(automation_id, **kwargs) -> SyncCursorPage[AutomationInvocation]
GET
/agents/automations/{automation_id}/invocations
Get an automation invocation
beta.agents.automations.invocations.retrieve(invocation_id, **kwargs) -> AutomationInvocation
GET
/agents/automations/{automation_id}/invocations/{invocation_id}
Models
class AutomationInvocation: …

One attempted delivery by an automation.

AutomationInvocationSource

AgentsEnvironments

Create an agent environment
beta.agents.environments.create(**kwargs) -> EnvironmentInfo
POST
/agents/environments
List agent environments
beta.agents.environments.list(**kwargs) -> SyncCursorPage[EnvironmentInfo]
GET
/agents/environments
Retrieve an agent environment
beta.agents.environments.retrieve(environment_id) -> EnvironmentInfo
GET
/agents/environments/{environment_id}
Models
class EnvironmentInfo: …

Safe metadata for a first-class execution environment.

AgentsEnvironmentsFiles

Write an agent environment file
beta.agents.environments.files.create(environment_id, **kwargs) -> EnvironmentFile
POST
/agents/environments/{environment_id}/files
List agent environment files
beta.agents.environments.files.list(environment_id, **kwargs) -> SyncTokenPage[EnvironmentFile]
GET
/agents/environments/{environment_id}/files
Models
class EnvironmentFile: …

A live file in an execution environment.

AgentsEnvironmentsTemplates

Create an agent environment template
beta.agents.environments.templates.create(**kwargs) -> EnvironmentTemplate
POST
/agents/environments/templates
Delete an agent environment template
beta.agents.environments.templates.delete(environment_template_id) -> EnvironmentTemplateDeleted
DELETE
/agents/environments/templates/{environment_template_id}
List agent environment templates
beta.agents.environments.templates.list(**kwargs) -> SyncCursorPage[EnvironmentTemplate]
GET
/agents/environments/templates
Retrieve an agent environment template
beta.agents.environments.templates.retrieve(environment_template_id) -> EnvironmentTemplate
GET
/agents/environments/templates/{environment_template_id}
Update an agent environment template
beta.agents.environments.templates.update(environment_template_id, **kwargs) -> EnvironmentTemplate
POST
/agents/environments/templates/{environment_template_id}
Models
class EnvironmentTemplate: …

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

class EnvironmentTemplateDeleted: …

A deleted reusable environment template.

AgentsSessions

Create an agent session
beta.agents.sessions.create(**kwargs) -> AgentSession
POST
/agents/sessions
Delete an agent session
beta.agents.sessions.delete(session_id) -> AgentSessionDeleted
DELETE
/agents/sessions/{session_id}
List agent sessions
beta.agents.sessions.list(**kwargs) -> SyncCursorPage[AgentSession]
GET
/agents/sessions
Retrieve an agent session
beta.agents.sessions.retrieve(session_id) -> AgentSession
GET
/agents/sessions/{session_id}
Update an agent session
beta.agents.sessions.update(session_id, **kwargs) -> AgentSession
POST
/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content
beta.agents.sessions.artifacts.content(artifact_id, **kwargs) -> BinaryResponseContent
GET
/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
beta.agents.sessions.artifacts.delete(artifact_id, **kwargs) -> SessionArtifactDeleted
DELETE
/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
beta.agents.sessions.artifacts.list(session_id, **kwargs) -> SyncCursorPage[SessionArtifact]
GET
/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
beta.agents.sessions.artifacts.retrieve(artifact_id, **kwargs) -> SessionArtifact
GET
/agents/sessions/{session_id}/artifacts/{artifact_id}
Models
class SessionArtifact: …

An immutable file published by a completed hosted session turn.

class SessionArtifactDeleted: …

Confirmation that an immutable session artifact was deleted.

AgentsSessionsEvents

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

AgentsSessionsItems

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

AgentsSessionsSubagents

List session subagents
beta.agents.sessions.subagents.list(session_id, **kwargs) -> SyncCursorPage[Subagent]
GET
/agents/sessions/{session_id}/subagents
Retrieve a session subagent
beta.agents.sessions.subagents.retrieve(subagent_id, **kwargs) -> Subagent
GET
/agents/sessions/{session_id}/subagents/{subagent_id}

AgentsSessionsSubagentsItems

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

AgentsSessionsSubagentsTurns

List subagent turns
beta.agents.sessions.subagents.turns.list(subagent_id, **kwargs) -> SyncCursorPage[Turn]
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
beta.agents.sessions.subagents.turns.retrieve(turn_id, **kwargs) -> Turn
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

AgentsSessionsSubagentsTurnsItems

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

AgentsSessionsTraces

List agent session traces
beta.agents.sessions.traces.list(session_id, **kwargs) -> SyncCursorPage[SessionTrace]
GET
/agents/sessions/{session_id}/traces
Models
class SessionTrace: …

AgentsSessionsTurns

List agent session turns
beta.agents.sessions.turns.list(session_id, **kwargs) -> SyncCursorPage[Turn]
GET
/agents/sessions/{session_id}/turns
Retrieve an agent session turn
beta.agents.sessions.turns.retrieve(turn_id, **kwargs) -> Turn
GET
/agents/sessions/{session_id}/turns/{turn_id}
Models
class Turn: …

The canonical public representation of a session turn.

AgentsSessionsTurnsItems

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

AgentsVaults

Create a vault
beta.agents.vaults.create(**kwargs) -> Vault
POST
/vaults
Delete a vault
beta.agents.vaults.delete(vault_id) -> VaultDeleted
DELETE
/vaults/{vault_id}
List vaults
beta.agents.vaults.list(**kwargs) -> SyncCursorPage[Vault]
GET
/vaults
Retrieve a vault
beta.agents.vaults.retrieve(vault_id) -> Vault
GET
/vaults/{vault_id}
Update a vault
beta.agents.vaults.update(vault_id, **kwargs) -> Vault
POST
/vaults/{vault_id}
Models
class Vault: …

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

class VaultDeleted: …

Confirmation that a vault was deleted.

Literal["active", "archived"]

Whether a vault or credential is active or archived.

Union[VaultStatus, List[VaultStatus]]

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

AgentsVaultsCredentials

Create a vault credential
beta.agents.vaults.credentials.create(vault_id, **kwargs) -> Credential
POST
/vaults/{vault_id}/credentials
Delete a vault credential
beta.agents.vaults.credentials.delete(credential_id, **kwargs) -> CredentialDeleted
DELETE
/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
beta.agents.vaults.credentials.list(vault_id, **kwargs) -> SyncCursorPage[Credential]
GET
/vaults/{vault_id}/credentials
Retrieve a vault credential
beta.agents.vaults.credentials.retrieve(credential_id, **kwargs) -> Credential
GET
/vaults/{vault_id}/credentials/{credential_id}
Update a vault credential
beta.agents.vaults.credentials.update(credential_id, **kwargs) -> Credential
POST
/vaults/{vault_id}/credentials/{credential_id}
Models
class Credential: …

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

CredentialAuth

The authentication configuration of a vault credential, excluding secrets.

CredentialAuthCreateParam

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

CredentialAuthRotateParam

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

class CredentialDeleted: …

Confirmation that a vault credential was deleted.

CredentialNetworking

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

CredentialNetworkingParam

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

McpOauthTokenEndpointAuth

The client authentication method used for OAuth token refresh.

McpOauthTokenEndpointAuthCreateParam

Client authentication credentials for OAuth token refresh.

McpOauthTokenEndpointAuthRotateParam

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