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
Agent beta().agents().create(params, requestOptions = RequestOptions.none())
POST
/agents
Delete an agent
AgentDeleted beta().agents().delete(params = AgentDeleteParams.none(), requestOptions = RequestOptions.none())
DELETE
/agents/{agent_id}
List agents
AgentListPage beta().agents().list(params = AgentListParams.none(), requestOptions = RequestOptions.none())
GET
/agents
Retrieve an agent
Agent beta().agents().retrieve(params = AgentRetrieveParams.none(), requestOptions = RequestOptions.none())
GET
/agents/{agent_id}
Update an agent
Agent beta().agents().update(params = AgentUpdateParams.none(), requestOptions = RequestOptions.none())
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.

class AgentContent:
union

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.

class AgentFunctionCallOutput:
union

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

class AgentFunctionCallOutputParam:
union

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

enum AgentFunctionCallStatus:

The status of a tool call.

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.

class AgentOutputItem:
union

An output item produced by an agent.

enum AgentOutputItemStatus:

The status of an agent output item.

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.

class AgentSessionEvent:
union

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.

class AgentSessionInputParam:
union

Input submitted to an existing session.

class AgentSessionItem:
union

An item associated with a session turn.

class AgentSessionMessage:

A user or assistant message recorded in a session.

class AgentSessionMessageContent:
union

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.

class AgentTool:
union

A tool available to the agent.

class AgentToolParam:
union

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.

class Environment:
union

The execution environment for a session.

class EnvironmentParam:
union

The execution environment and optional reusable template for a session.

class HostedEnvironmentFile:
union

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

class HostedEnvironmentFileId:

A file copied from the OpenAI Files API.

class HostedEnvironmentFileParam:
union

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.

class HostedSkill:
union

A skill installed in an OpenAI-hosted environment.

class HostedSkillParam:
union

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.

class InputContent:
union

User-provided content recorded in a session item.

class InputContentParam:
union

Content included in an input message.

class McpTransport:
union

The transport used to connect to an MCP server.

class McpTransportParam:
union

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.

class PersistedAgentTool:
union

A credential-free tool available to a reusable agent.

class PersistedAgentToolParam:
union

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

class PersistedMcpTransport:
union

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

class PersistedMcpTransportParam:
union

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.

class TextFormat:
union

The effective output format for generated text.

class TextFormatParam:
union

The output format for generated text.

class TokenUsage:

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

class WebSearchAction:
union

An action performed by the web search tool.

AgentsAutomations

AgentsAutomationsInvocations

AgentsEnvironments

Create an agent environment
EnvironmentInfo beta().agents().environments().create(params, requestOptions = RequestOptions.none())
POST
/agents/environments
List agent environments
EnvironmentListPage beta().agents().environments().list(params = EnvironmentListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/environments
Retrieve an agent environment
EnvironmentInfo beta().agents().environments().retrieve(params = EnvironmentRetrieveParams.none(), requestOptions = RequestOptions.none())
GET
/agents/environments/{environment_id}
Models
class EnvironmentInfo:

Safe metadata for a first-class execution environment.

AgentsEnvironmentsFiles

Write an agent environment file
EnvironmentFile beta().agents().environments().files().create(params = FileCreateParams.none(), requestOptions = RequestOptions.none())
POST
/agents/environments/{environment_id}/files
List agent environment files
FileListPage beta().agents().environments().files().list(params = FileListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/environments/{environment_id}/files
Models
class EnvironmentFile:

A live file in an execution environment.

AgentsEnvironmentsTemplates

Create an agent environment template
EnvironmentTemplate beta().agents().environments().templates().create(params = TemplateCreateParams.none(), requestOptions = RequestOptions.none())
POST
/agents/environments/templates
Delete an agent environment template
EnvironmentTemplateDeleted beta().agents().environments().templates().delete(params = TemplateDeleteParams.none(), requestOptions = RequestOptions.none())
DELETE
/agents/environments/templates/{environment_template_id}
List agent environment templates
TemplateListPage beta().agents().environments().templates().list(params = TemplateListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/environments/templates
Retrieve an agent environment template
EnvironmentTemplate beta().agents().environments().templates().retrieve(params = TemplateRetrieveParams.none(), requestOptions = RequestOptions.none())
GET
/agents/environments/templates/{environment_template_id}
Update an agent environment template
EnvironmentTemplate beta().agents().environments().templates().update(params = TemplateUpdateParams.none(), requestOptions = RequestOptions.none())
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
AgentSession beta().agents().sessions().create(params, requestOptions = RequestOptions.none())
POST
/agents/sessions
Delete an agent session
AgentSessionDeleted beta().agents().sessions().delete(params = SessionDeleteParams.none(), requestOptions = RequestOptions.none())
DELETE
/agents/sessions/{session_id}
List agent sessions
SessionListPage beta().agents().sessions().list(params = SessionListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions
Retrieve an agent session
AgentSession beta().agents().sessions().retrieve(params = SessionRetrieveParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}
Update an agent session
AgentSession beta().agents().sessions().update(params = SessionUpdateParams.none(), requestOptions = RequestOptions.none())
POST
/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content
HttpResponse beta().agents().sessions().artifacts().content(params, requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
SessionArtifactDeleted beta().agents().sessions().artifacts().delete(params, requestOptions = RequestOptions.none())
DELETE
/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
ArtifactListPage beta().agents().sessions().artifacts().list(params = ArtifactListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
SessionArtifact beta().agents().sessions().artifacts().retrieve(params, requestOptions = RequestOptions.none())
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(params, requestOptions = RequestOptions.none())
POST
/agents/sessions/{session_id}/events
Stream agent session events
AgentSessionEvent beta().agents().sessions().events().streamStreaming(params = EventStreamParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/events

AgentsSessionsItems

List agent session items
ItemListPage beta().agents().sessions().items().list(params = ItemListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/items

AgentsSessionsSubagents

List session subagents
SubagentListPage beta().agents().sessions().subagents().list(params = SubagentListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/subagents
Retrieve a session subagent
Subagent beta().agents().sessions().subagents().retrieve(params, requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/subagents/{subagent_id}

AgentsSessionsSubagentsItems

List subagent items
ItemListPage beta().agents().sessions().subagents().items().list(params, requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/items

AgentsSessionsSubagentsTurns

List subagent turns
TurnListPage beta().agents().sessions().subagents().turns().list(params, requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
Turn beta().agents().sessions().subagents().turns().retrieve(params, requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

AgentsSessionsSubagentsTurnsItems

List subagent turn items
ItemListPage beta().agents().sessions().subagents().turns().items().list(params, requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items

AgentsSessionsTraces

List agent session traces
TraceListPage beta().agents().sessions().traces().list(params = TraceListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/traces
Models
class SessionTrace:

AgentsSessionsTurns

List agent session turns
TurnListPage beta().agents().sessions().turns().list(params = TurnListParams.none(), requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/turns
Retrieve an agent session turn
Turn beta().agents().sessions().turns().retrieve(params, requestOptions = RequestOptions.none())
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
ItemListPage beta().agents().sessions().turns().items().list(params, requestOptions = RequestOptions.none())
GET
/agents/sessions/{session_id}/turns/{turn_id}/items

AgentsVaults

Create a vault
Vault beta().agents().vaults().create(params = VaultCreateParams.none(), requestOptions = RequestOptions.none())
POST
/vaults
Delete a vault
VaultDeleted beta().agents().vaults().delete(params = VaultDeleteParams.none(), requestOptions = RequestOptions.none())
DELETE
/vaults/{vault_id}
List vaults
VaultListPage beta().agents().vaults().list(params = VaultListParams.none(), requestOptions = RequestOptions.none())
GET
/vaults
Retrieve a vault
Vault beta().agents().vaults().retrieve(params = VaultRetrieveParams.none(), requestOptions = RequestOptions.none())
GET
/vaults/{vault_id}
Update a vault
Vault beta().agents().vaults().update(params = VaultUpdateParams.none(), requestOptions = RequestOptions.none())
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.

enum VaultStatus:

Whether a vault or credential is active or archived.

class VaultStatusFilter:
union

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

AgentsVaultsCredentials

Create a vault credential
Credential beta().agents().vaults().credentials().create(params, requestOptions = RequestOptions.none())
POST
/vaults/{vault_id}/credentials
Delete a vault credential
CredentialDeleted beta().agents().vaults().credentials().delete(params, requestOptions = RequestOptions.none())
DELETE
/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
CredentialListPage beta().agents().vaults().credentials().list(params = CredentialListParams.none(), requestOptions = RequestOptions.none())
GET
/vaults/{vault_id}/credentials
Retrieve a vault credential
Credential beta().agents().vaults().credentials().retrieve(params, requestOptions = RequestOptions.none())
GET
/vaults/{vault_id}/credentials/{credential_id}
Update a vault credential
Credential beta().agents().vaults().credentials().update(params, requestOptions = RequestOptions.none())
POST
/vaults/{vault_id}/credentials/{credential_id}
Models
class Credential:

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

class CredentialAuth:
union

The authentication configuration of a vault credential, excluding secrets.

class CredentialAuthCreateParam:
union

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

class CredentialAuthRotateParam:
union

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

class CredentialDeleted:

Confirmation that a vault credential was deleted.

class CredentialNetworking:
union

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

class CredentialNetworkingParam:
union

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

class McpOAuthTokenEndpointAuth:
union

The client authentication method used for OAuth token refresh.

class McpOAuthTokenEndpointAuthCreateParam:
union

Client authentication credentials for OAuth token refresh.

class McpOAuthTokenEndpointAuthRotateParam:
union

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