API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Agents

Create an agent

beta.agents.create(AgentCreateParams**kwargs) -> Agent

POST/agents

Delete an agent

beta.agents.delete(stragent_id) -> AgentDeleted

DELETE/agents/{agent_id}

List agents

beta.agents.list(AgentListParams**kwargs) -> SyncCursorPage[Agent]

GET/agents

Retrieve an agent

beta.agents.retrieve(stragent_id) -> Agent

GET/agents/{agent_id}

Update an agent

beta.agents.update(stragent_id, AgentUpdateParams**kwargs) -> Agent

POST/agents/{agent_id}

ModelsExpand Collapse

class Agent: …

A reusable agent scoped to the caller’s project.

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 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 AgentSessionEnvironmentState: …

The current state of a session environment.

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.

AgentsEnvironments

Retrieve an agent environment

beta.agents.environments.retrieve(strenvironment_id) -> EnvironmentInfo

GET/agents/environments/{environment_id}

ModelsExpand Collapse

class EnvironmentInfo: …

Safe metadata for a first-class execution environment.

AgentsEnvironmentsFiles

Create an agent environment file

beta.agents.environments.files.create(strenvironment_id, FileCreateParams**kwargs) -> EnvironmentFile

POST/agents/environments/{environment_id}/files

List agent environment files

beta.agents.environments.files.list(strenvironment_id, FileListParams**kwargs) -> SyncTokenPage[EnvironmentFile]

GET/agents/environments/{environment_id}/files

ModelsExpand Collapse

class EnvironmentFile: …

A live file in an execution environment.

AgentsEnvironmentsTemplates

Create an agent environment template

beta.agents.environments.templates.create(TemplateCreateParams**kwargs) -> EnvironmentTemplate

POST/agents/environments/templates

Delete an agent environment template

beta.agents.environments.templates.delete(strenvironment_template_id) -> EnvironmentTemplateDeleted

DELETE/agents/environments/templates/{environment_template_id}

List agent environment templates

beta.agents.environments.templates.list(TemplateListParams**kwargs) -> SyncCursorPage[EnvironmentTemplate]

GET/agents/environments/templates

Retrieve an agent environment template

beta.agents.environments.templates.retrieve(strenvironment_template_id) -> EnvironmentTemplate

GET/agents/environments/templates/{environment_template_id}

Update an agent environment template

beta.agents.environments.templates.update(strenvironment_template_id, TemplateUpdateParams**kwargs) -> EnvironmentTemplate

POST/agents/environments/templates/{environment_template_id}

ModelsExpand Collapse

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(SessionCreateParams**kwargs) -> AgentSession

POST/agents/sessions

Delete an agent session

beta.agents.sessions.delete(strsession_id) -> AgentSessionDeleted

DELETE/agents/sessions/{session_id}

List agent sessions

beta.agents.sessions.list(SessionListParams**kwargs) -> SyncCursorPage[AgentSession]

GET/agents/sessions

Retrieve an agent session

beta.agents.sessions.retrieve(strsession_id) -> AgentSession

GET/agents/sessions/{session_id}

Update an agent session

beta.agents.sessions.update(strsession_id, SessionUpdateParams**kwargs) -> AgentSession

POST/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content

beta.agents.sessions.artifacts.content(strartifact_id, ArtifactContentParams**kwargs) -> BinaryResponseContent

GET/agents/sessions/{session_id}/artifacts/{artifact_id}/content

Delete an agent session artifact

beta.agents.sessions.artifacts.delete(strartifact_id, ArtifactDeleteParams**kwargs) -> SessionArtifactDeleted

DELETE/agents/sessions/{session_id}/artifacts/{artifact_id}

List agent session artifacts

beta.agents.sessions.artifacts.list(strsession_id, ArtifactListParams**kwargs) -> SyncCursorPage[SessionArtifact]

GET/agents/sessions/{session_id}/artifacts

Retrieve an agent session artifact

beta.agents.sessions.artifacts.retrieve(strartifact_id, ArtifactRetrieveParams**kwargs) -> SessionArtifact

GET/agents/sessions/{session_id}/artifacts/{artifact_id}

ModelsExpand Collapse

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(strsession_id, EventCreateParams**kwargs)

POST/agents/sessions/{session_id}/events

Stream agent session events

beta.agents.sessions.events.stream(strsession_id) -> AgentSessionEvent

GET/agents/sessions/{session_id}/events

AgentsSessionsItems

List agent session items

beta.agents.sessions.items.list(strsession_id, ItemListParams**kwargs) -> SyncCursorPage[AgentSessionItem]

GET/agents/sessions/{session_id}/items

AgentsSessionsSubagents

List session subagents

beta.agents.sessions.subagents.list(strsession_id, SubagentListParams**kwargs) -> SyncCursorPage[Subagent]

GET/agents/sessions/{session_id}/subagents

Retrieve a session subagent

beta.agents.sessions.subagents.retrieve(strsubagent_id, SubagentRetrieveParams**kwargs) -> Subagent

GET/agents/sessions/{session_id}/subagents/{subagent_id}

AgentsSessionsSubagentsItems

List subagent items

beta.agents.sessions.subagents.items.list(strsubagent_id, ItemListParams**kwargs) -> SyncCursorPage[AgentSessionItem]

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

AgentsSessionsSubagentsTurns

List subagent turns

beta.agents.sessions.subagents.turns.list(strsubagent_id, TurnListParams**kwargs) -> SyncCursorPage[Turn]

GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns

Retrieve a subagent turn

beta.agents.sessions.subagents.turns.retrieve(strturn_id, TurnRetrieveParams**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(strturn_id, ItemListParams**kwargs) -> SyncCursorPage[AgentSessionItem]

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

AgentsSessionsTurns

List agent session turns

beta.agents.sessions.turns.list(strsession_id, TurnListParams**kwargs) -> SyncCursorPage[Turn]

GET/agents/sessions/{session_id}/turns

Retrieve an agent session turn

beta.agents.sessions.turns.retrieve(strturn_id, TurnRetrieveParams**kwargs) -> Turn

GET/agents/sessions/{session_id}/turns/{turn_id}

ModelsExpand Collapse

class Turn: …

The canonical public representation of a session turn.

AgentsVaults

Create a vault

beta.agents.vaults.create(VaultCreateParams**kwargs) -> Vault

POST/vaults

Delete a vault

beta.agents.vaults.delete(strvault_id) -> VaultDeleted

DELETE/vaults/{vault_id}

List vaults

beta.agents.vaults.list(VaultListParams**kwargs) -> SyncCursorPage[Vault]

GET/vaults

Retrieve a vault

beta.agents.vaults.retrieve(strvault_id) -> Vault

GET/vaults/{vault_id}

ModelsExpand Collapse

class Vault: …

A collection of credentials that agent tools can use to authenticate to MCP servers.

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(strvault_id, CredentialCreateParams**kwargs) -> Credential

POST/vaults/{vault_id}/credentials

Delete a vault credential

beta.agents.vaults.credentials.delete(strcredential_id, CredentialDeleteParams**kwargs) -> CredentialDeleted

DELETE/vaults/{vault_id}/credentials/{credential_id}

List vault credentials

beta.agents.vaults.credentials.list(strvault_id, CredentialListParams**kwargs) -> SyncCursorPage[Credential]

GET/vaults/{vault_id}/credentials

Retrieve a vault credential

beta.agents.vaults.credentials.retrieve(strcredential_id, CredentialRetrieveParams**kwargs) -> Credential

GET/vaults/{vault_id}/credentials/{credential_id}

Rotate a vault credential

beta.agents.vaults.credentials.update(strcredential_id, CredentialUpdateParams**kwargs) -> Credential

POST/vaults/{vault_id}/credentials/{credential_id}

ModelsExpand Collapse

class Credential: …

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

CredentialAuth

The MCP server and authentication configuration of a vault credential, excluding secrets.

CredentialAuthCreateParam

Authentication credentials for an MCP server used by agent tools.

CredentialAuthRotateParam

Updates to a vault credential without changing its authentication method or MCP server.

class CredentialDeleted: …

Confirmation that a vault credential was deleted.

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.