API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Agents

Create an agent

Agent beta().agents().create(AgentCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

POST/agents

Delete an agent

AgentDeleted beta().agents().delete(AgentDeleteParamsparams = AgentDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

DELETE/agents/{agent_id}

List agents

AgentListPage beta().agents().list(AgentListParamsparams = AgentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents

Retrieve an agent

Agent beta().agents().retrieve(AgentRetrieveParamsparams = AgentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/{agent_id}

Update an agent

Agent beta().agents().update(AgentUpdateParamsparams = AgentUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

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.

class AgentContent: A class that can be one of several variants.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: A class that can be one of several variants.union

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

class AgentFunctionCallOutputParam: A class that can be one of several variants.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: A class that can be one of several variants.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 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.

class AgentSessionEvent: A class that can be one of several variants.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: A class that can be one of several variants.union

Input submitted to an existing session.

class AgentSessionItem: A class that can be one of several variants.union

An item associated with a session turn.

class AgentSessionMessage:

A user or assistant message recorded in a session.

class AgentSessionMessageContent: A class that can be one of several variants.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: A class that can be one of several variants.union

A tool available to the agent.

class AgentToolParam: A class that can be one of several variants.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: A class that can be one of several variants.union

The execution environment for a session.

class EnvironmentParam: A class that can be one of several variants.union

The execution environment and optional reusable template for a session.

class HostedEnvironmentFile: A class that can be one of several variants.union

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

class HostedEnvironmentFileId:

A file copied from the OpenAI Files API.

class HostedEnvironmentFileParam: A class that can be one of several variants.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: A class that can be one of several variants.union

A skill installed in an OpenAI-hosted environment.

class HostedSkillParam: A class that can be one of several variants.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: A class that can be one of several variants.union

User-provided content recorded in a session item.

class InputContentParam: A class that can be one of several variants.union

Content included in an input message.

class McpTransport: A class that can be one of several variants.union

The transport used to connect to an MCP server.

class McpTransportParam: A class that can be one of several variants.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: A class that can be one of several variants.union

A credential-free tool available to a reusable agent.

class PersistedAgentToolParam: A class that can be one of several variants.union

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

class PersistedMcpTransport: A class that can be one of several variants.union

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

class PersistedMcpTransportParam: A class that can be one of several variants.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: A class that can be one of several variants.union

The effective output format for generated text.

class TextFormatParam: A class that can be one of several variants.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: A class that can be one of several variants.union

An action performed by the web search tool.

AgentsEnvironments

Retrieve an agent environment

EnvironmentInfo beta().agents().environments().retrieve(EnvironmentRetrieveParamsparams = EnvironmentRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/environments/{environment_id}

ModelsExpand Collapse

class EnvironmentInfo:

Safe metadata for a first-class execution environment.

AgentsEnvironmentsFiles

Create an agent environment file

EnvironmentFile beta().agents().environments().files().create(FileCreateParamsparams = FileCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

POST/agents/environments/{environment_id}/files

List agent environment files

FileListPage beta().agents().environments().files().list(FileListParamsparams = FileListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/environments/{environment_id}/files

ModelsExpand Collapse

class EnvironmentFile:

A live file in an execution environment.

AgentsEnvironmentsTemplates

Create an agent environment template

EnvironmentTemplate beta().agents().environments().templates().create(TemplateCreateParamsparams = TemplateCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

POST/agents/environments/templates

Delete an agent environment template

EnvironmentTemplateDeleted beta().agents().environments().templates().delete(TemplateDeleteParamsparams = TemplateDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

DELETE/agents/environments/templates/{environment_template_id}

List agent environment templates

TemplateListPage beta().agents().environments().templates().list(TemplateListParamsparams = TemplateListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/environments/templates

Retrieve an agent environment template

EnvironmentTemplate beta().agents().environments().templates().retrieve(TemplateRetrieveParamsparams = TemplateRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/environments/templates/{environment_template_id}

Update an agent environment template

EnvironmentTemplate beta().agents().environments().templates().update(TemplateUpdateParamsparams = TemplateUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

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

AgentSession beta().agents().sessions().create(SessionCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

POST/agents/sessions

Delete an agent session

AgentSessionDeleted beta().agents().sessions().delete(SessionDeleteParamsparams = SessionDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

DELETE/agents/sessions/{session_id}

List agent sessions

SessionListPage beta().agents().sessions().list(SessionListParamsparams = SessionListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/sessions

Retrieve an agent session

AgentSession beta().agents().sessions().retrieve(SessionRetrieveParamsparams = SessionRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/sessions/{session_id}

Update an agent session

AgentSession beta().agents().sessions().update(SessionUpdateParamsparams = SessionUpdateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

POST/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content

HttpResponse beta().agents().sessions().artifacts().content(ArtifactContentParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

Delete an agent session artifact

SessionArtifactDeleted beta().agents().sessions().artifacts().delete(ArtifactDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

List agent session artifacts

ArtifactListPage beta().agents().sessions().artifacts().list(ArtifactListParamsparams = ArtifactListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/sessions/{session_id}/artifacts

Retrieve an agent session artifact

SessionArtifact beta().agents().sessions().artifacts().retrieve(ArtifactRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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(EventCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

POST/agents/sessions/{session_id}/events

Stream agent session events

AgentSessionEvent beta().agents().sessions().events().streamStreaming(EventStreamParamsparams = EventStreamParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/sessions/{session_id}/events

AgentsSessionsItems

List agent session items

ItemListPage beta().agents().sessions().items().list(ItemListParamsparams = ItemListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/sessions/{session_id}/items

AgentsSessionsSubagents

List session subagents

SubagentListPage beta().agents().sessions().subagents().list(SubagentListParamsparams = SubagentListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/sessions/{session_id}/subagents

Retrieve a session subagent

Subagent beta().agents().sessions().subagents().retrieve(SubagentRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

AgentsSessionsSubagentsItems

List subagent items

ItemListPage beta().agents().sessions().subagents().items().list(ItemListParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

AgentsSessionsSubagentsTurns

List subagent turns

TurnListPage beta().agents().sessions().subagents().turns().list(TurnListParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

Retrieve a subagent turn

Turn beta().agents().sessions().subagents().turns().retrieve(TurnRetrieveParamsparams, RequestOptionsrequestOptions = 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(ItemListParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

AgentsSessionsTurns

List agent session turns

TurnListPage beta().agents().sessions().turns().list(TurnListParamsparams = TurnListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/agents/sessions/{session_id}/turns

Retrieve an agent session turn

Turn beta().agents().sessions().turns().retrieve(TurnRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

ModelsExpand Collapse

class Turn:

The canonical public representation of a session turn.

AgentsVaults

Create a vault

Vault beta().agents().vaults().create(VaultCreateParamsparams = VaultCreateParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

POST/vaults

Delete a vault

VaultDeleted beta().agents().vaults().delete(VaultDeleteParamsparams = VaultDeleteParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

DELETE/vaults/{vault_id}

List vaults

VaultListPage beta().agents().vaults().list(VaultListParamsparams = VaultListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/vaults

Retrieve a vault

Vault beta().agents().vaults().retrieve(VaultRetrieveParamsparams = VaultRetrieveParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/vaults/{vault_id}

ModelsExpand Collapse

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: A class that can be one of several variants.union

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

AgentsVaultsCredentials

Create a vault credential

Credential beta().agents().vaults().credentials().create(CredentialCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

POST/vaults/{vault_id}/credentials

Delete a vault credential

CredentialDeleted beta().agents().vaults().credentials().delete(CredentialDeleteParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

List vault credentials

CredentialListPage beta().agents().vaults().credentials().list(CredentialListParamsparams = CredentialListParams.none(), RequestOptionsrequestOptions = RequestOptions.none())

GET/vaults/{vault_id}/credentials

Retrieve a vault credential

Credential beta().agents().vaults().credentials().retrieve(CredentialRetrieveParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

Rotate a vault credential

Credential beta().agents().vaults().credentials().update(CredentialUpdateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

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

ModelsExpand Collapse

class Credential:

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

class CredentialAuth: A class that can be one of several variants.union

The authentication configuration of a vault credential, excluding secrets.

class CredentialAuthCreateParam: A class that can be one of several variants.union

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

class CredentialAuthRotateParam: A class that can be one of several variants.union

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

class CredentialDeleted:

Confirmation that a vault credential was deleted.

class McpOAuthTokenEndpointAuth: A class that can be one of several variants.union

The client authentication method used for OAuth token refresh.

class McpOAuthTokenEndpointAuthCreateParam: A class that can be one of several variants.union

Client authentication credentials for OAuth token refresh.

class McpOAuthTokenEndpointAuthRotateParam: A class that can be one of several variants.union

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