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
API Reference
Beta

Agents

Create an agent
beta.agents.create(**kwargs) -> Agent { id, created_at, instructions, 10 more }
POST/agents
Delete an agent
beta.agents.delete(agent_id) -> AgentDeleted { id, deleted, object }
DELETE/agents/{agent_id}
List agents
beta.agents.list(**kwargs) -> CursorPage<Agent { id, created_at, instructions, 10 more } >
GET/agents
Retrieve an agent
beta.agents.retrieve(agent_id) -> Agent { id, created_at, instructions, 10 more }
GET/agents/{agent_id}
Update an agent
beta.agents.update(agent_id, **kwargs) -> Agent { id, created_at, instructions, 10 more }
POST/agents/{agent_id}
ModelsExpand Collapse
class Agent { id, created_at, instructions, 10 more }

A reusable agent scoped to the caller’s project.

class AgentCloseSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

A request to close a subagent.

class AgentCommandExecutionItem { id, command, cwd, 6 more }

A command execution produced by the agent.

AgentContent = OutputText { text, type } | EncryptedContent{ encrypted_content, type}

A plaintext or encrypted content part exchanged between agents.

class AgentCreateSubagentCallItem { id, agent_id, content, 5 more }

A request to spawn a subagent.

class AgentDeleted { id, deleted, object }

A deleted reusable agent.

class AgentFunctionCallItem { id, arguments, call_id, 4 more }

A function call produced by the agent.

AgentFunctionCallOutput = String | Array[InputContent]

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

AgentFunctionCallOutputParam = String | Array[InputContentParam]

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

AgentFunctionCallStatus = :in_progress | :completed | :failed | :incomplete

The status of a tool call.

class AgentInterruptSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

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

class AgentMcpCallItem { id, arguments, error, 6 more }

A call to a tool on an MCP server.

class AgentOutputCommandExecutionOutputDeltaEvent { delta, event_id, item_id, 4 more }

Emitted when command execution produces an output delta.

AgentOutputItem = AgentSessionAssistantMessage { id, content, phase, 4 more } | AgentReasoningItem { id, status, summary, 2 more } | AgentFunctionCallItem { id, arguments, call_id, 4 more } | 9 more

An output item produced by an agent.

AgentOutputItemStatus = :in_progress | :completed | :incomplete

The status of an agent output item.

class AgentReasoning { effort, summary }

The reasoning configuration used by an agent.

class AgentReasoningItem { id, status, summary, 2 more }

A reasoning item produced by the agent.

class AgentReasoningParam { effort, summary }

Reasoning configuration for the agent.

class AgentResumeSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

A request to resume a subagent.

class AgentSendSubagentInputCallItem { id, content, recipient_agent_id, 4 more }

A request to send input to another agent.

class AgentSession { id, agent, created_at, 9 more }

A Managed Agents session.

class AgentSessionAssistantMessage { id, content, phase, 4 more }

An assistant message produced by the agent.

class AgentSessionCreatedEvent { event_id, session, type }

Emitted when a session is created.

class AgentSessionDeleted { id, deleted, object }

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

class AgentSessionEnvironmentConnectedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment connects.

class AgentSessionEnvironmentDisconnectedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment disconnects.

class AgentSessionEnvironmentFailedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment fails.

class AgentSessionEnvironmentPendingEvent { environment, event_id, session_id, 2 more }

Emitted while a session environment is being prepared.

class AgentSessionEnvironmentReadyEvent { environment, event_id, session_id, 2 more }

Emitted when a hosted session environment is ready to connect.

class AgentSessionEnvironmentState { id, error, status, type }

The current state of a session environment.

class AgentSessionErrorEvent { error, event_id, session_id, type }

Emitted when a turn or session fails.

AgentSessionEvent = AgentSessionErrorEvent { error, event_id, session_id, type } | AgentSessionEnvironmentReadyEvent { environment, event_id, session_id, 2 more } | AgentSessionEnvironmentReset{ environment_id, event_id, reset_count, 3 more} | 28 more

An event emitted by a Managed Agents session.

class AgentSessionFailedEvent { event_id, session, type }

Emitted when a session fails.

class AgentSessionIdleEvent { event_id, session, type }

Emitted when a session becomes idle.

class AgentSessionInProgressEvent { event_id, session, type }

Emitted when a session starts processing a turn.

class AgentSessionInputMessageParam { content, role, type }

A user message submitted to a session.

AgentSessionInputParam = AgentSessionInputMessage{ input, type} | AgentSessionInputCancel{ type} | AgentSessionInputToolResult{ call_id, success, turn_id, 3 more}

Input submitted to an existing session.

AgentSessionItem = AgentSessionMessage { id, content, phase, 4 more } | AgentReasoningItem { id, status, summary, 2 more } | AgentFunctionCallItem { id, arguments, call_id, 4 more } | 11 more

An item associated with a session turn.

class AgentSessionMessage { id, content, phase, 4 more }

A user or assistant message recorded in a session.

AgentSessionMessageContent = InputText{ text, type} | InputImage{ image_url, type} | OutputText{ text, type}

A content part in a session message.

class AgentSessionRequiresActionEvent { event_id, session, type }

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

class AgentSessionSubagentActiveEvent { event_id, subagent, type }

Emitted when a closed subagent successfully resumes.

class AgentSessionSubagentClosedEvent { event_id, subagent, type }

Emitted when a subagent is closed.

class AgentSessionSubagentCreatedEvent { event_id, subagent, type }

Emitted when a subagent is created.

class AgentSessionTurnCancelledEvent { event_id, session_id, turn, 3 more }

Emitted when a turn is cancelled.

class AgentSessionTurnCompletedEvent { event_id, session_id, turn, 3 more }

Emitted when a turn completes.

class AgentSessionTurnContentPartAddedEvent { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is added.

class AgentSessionTurnContentPartDoneEvent { content_index, event_id, item_id, 5 more }

Emitted when an output content part is complete.

class AgentSessionTurnCreatedEvent { event_id, session_id, turn, 2 more }

Emitted when a turn is created.

class AgentSessionTurnFailedEvent { event_id, session_id, turn, 3 more }

Emitted when a turn fails.

class AgentSessionTurnInProgressEvent { event_id, session_id, turn, 2 more }

Emitted when a turn starts running.

class AgentSessionTurnItemAddedEvent { event_id, item, output_index, 3 more }

Emitted when an item is added to a turn.

class AgentSessionTurnItemDoneEvent { event_id, item, output_index, 3 more }

Emitted when an output item is complete.

class AgentSessionTurnOutputTextDeltaEvent { content_index, delta, event_id, 5 more }

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

class AgentSessionTurnOutputTextDoneEvent { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is complete.

class AgentSessionTurnReasoningSummaryPartAddedEvent { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is added.

class AgentSessionTurnReasoningSummaryPartDoneEvent { event_id, item_id, output_index, 6 more }

Emitted when a reasoning summary part is complete.

class AgentSessionTurnReasoningSummaryTextDeltaEvent { delta, event_id, item_id, 5 more }

Emitted when text is appended to a reasoning summary.

class AgentSessionTurnReasoningSummaryTextDoneEvent { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is complete.

class AgentText { format_, verbosity }

The text configuration used by an agent.

class AgentTextParam { format_, verbosity }

Configuration for text generated by the agent.

AgentTool = Function{ defer_loading, description, name, 2 more} | ProgrammaticToolCalling{ enabled, type} | Mcp{ allowed_tools, connection_origin, credential_id, 5 more} | WebSearch{ allowed_domains, context_size, location, 2 more}

A tool available to the agent.

AgentToolParam = Function{ description, name, parameters, 2 more} | ToolSearch{ type} | ProgrammaticToolCalling{ type, enabled} | 2 more

A tool available to the agent.

class AgentWaitForSubagentsCallItem { id, recipient_agent_ids, sender_agent_id, 3 more }

A request to wait for one or more subagents.

class AgentWebSearchCallItem { id, action, status, 2 more }

A web search call produced by the agent.

Environment = None{ type} | OpenAIHosted{ id, capability_directories, files, 5 more} | SelfHosted{ id, capability_directories, remote_url, 2 more}

The execution environment for a session.

EnvironmentParam = None{ type} | OpenAIHosted{ type, capability_directories, env, 7 more} | SelfHosted{ type, workspace_directory, capability_directories}

The execution environment and optional reusable template for a session.

HostedEnvironmentFile = HostedEnvironmentFileID { id, file_id, path, 2 more } | Inline{ id, path, size_bytes, type}

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

class HostedEnvironmentFileID { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

HostedEnvironmentFileParam = FileID{ file_id, path, type} | Inline{ data, path, type}

A file materialized in an OpenAI-hosted execution environment.

class HostedPlugin { description, name, type }

A plugin installed from an inline ZIP archive.

class HostedPluginParam { description, name, source, type }

Supplies a plugin ZIP directly in the session request.

HostedSkill = HostedSkillReference { description, name, skill_id, 2 more } | Inline{ description, name, type}

A skill installed in an OpenAI-hosted environment.

HostedSkillParam = SkillReference{ skill_id, type, version} | Inline{ description, name, source, type}

A skill installed in an OpenAI-hosted environment.

class HostedSkillReference { description, name, skill_id, 2 more }

A skill installed from the Skills API.

class InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

InputContent = InputText{ text, type} | InputImage{ image_url, type}

User-provided content recorded in a session item.

InputContentParam = InputText{ text, type} | InputImage{ image_url, type}

Content included in an input message.

McpTransport = HTTP{ server_url, type} | Stdio{ args, command, cwd, 2 more}

The transport used to connect to an MCP server.

McpTransportParam = HTTP{ server_url, type, authorization, headers} | Stdio{ command, cwd, type, 3 more}

The transport used to connect to an MCP server.

class MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

class MultiAgentConfigParam { enabled, max_concurrent_subagents }

Explicit configuration for creating and coordinating subagents.

class OutputText { text, type }

A text content part produced by the agent.

PersistedAgentTool = Function{ defer_loading, description, name, 2 more} | ToolSearch{ type} | ProgrammaticToolCalling{ enabled, type} | 2 more

A credential-free tool available to a reusable agent.

PersistedAgentToolParam = Function{ description, name, parameters, 2 more} | ToolSearch{ type} | ProgrammaticToolCalling{ type, enabled} | 2 more

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

PersistedMcpTransport = HTTP{ headers, server_url, type} | Stdio{ args, command, cwd, 2 more}

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

PersistedMcpTransportParam = HTTP{ server_url, type, headers} | Stdio{ command, cwd, type, 2 more}

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

class SessionError { code, message, param, type }

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

class SessionTurnError { code, message }

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

class SetupCommandParam { command, cwd }

A confidential setup command executed before the hosted agent starts.

class Subagent { id, closed_at, instructions, 6 more }

A subagent created within a session.

class SummaryText { text, type }

A reasoning summary content part.

TextFormat = Text{ type} | JSONSchema{ schema, type}

The effective output format for generated text.

TextFormatParam = Text{ type} | JSONSchema{ schema, type}

The output format for generated text.

class TokenUsage { 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} | OpenPage{ type, url} | FindInPage{ pattern, type, url} | Other{ type}

An action performed by the web search tool.

AgentsEnvironments

Retrieve an agent environment
beta.agents.environments.retrieve(environment_id) -> EnvironmentInfo { id, files, object, 4 more }
GET/agents/environments/{environment_id}
ModelsExpand Collapse
class EnvironmentInfo { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

AgentsEnvironmentsFiles

Create an agent environment file
beta.agents.environments.files.create(environment_id, **kwargs) -> EnvironmentFile { environment_id, object, path, size_bytes }
POST/agents/environments/{environment_id}/files
List agent environment files
beta.agents.environments.files.list(environment_id, **kwargs) -> TokenPage<EnvironmentFile { environment_id, object, path, size_bytes } >
GET/agents/environments/{environment_id}/files
ModelsExpand Collapse
class EnvironmentFile { environment_id, object, path, size_bytes }

A live file in an execution environment.

AgentsEnvironmentsTemplates

Create an agent environment template
beta.agents.environments.templates.create(**kwargs) -> EnvironmentTemplate { id, capability_directories, created_at, 8 more }
POST/agents/environments/templates
Delete an agent environment template
beta.agents.environments.templates.delete(environment_template_id) -> EnvironmentTemplateDeleted { id, deleted, object }
DELETE/agents/environments/templates/{environment_template_id}
List agent environment templates
beta.agents.environments.templates.list(**kwargs) -> CursorPage<EnvironmentTemplate { id, capability_directories, created_at, 8 more } >
GET/agents/environments/templates
Retrieve an agent environment template
beta.agents.environments.templates.retrieve(environment_template_id) -> EnvironmentTemplate { id, capability_directories, created_at, 8 more }
GET/agents/environments/templates/{environment_template_id}
Update an agent environment template
beta.agents.environments.templates.update(environment_template_id, **kwargs) -> EnvironmentTemplate { id, capability_directories, created_at, 8 more }
POST/agents/environments/templates/{environment_template_id}
ModelsExpand Collapse
class EnvironmentTemplate { id, capability_directories, created_at, 8 more }

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

class EnvironmentTemplateDeleted { id, deleted, object }

A deleted reusable environment template.

AgentsSessions

Create an agent session
beta.agents.sessions.create(**kwargs) -> AgentSession { id, agent, created_at, 9 more }
POST/agents/sessions
Delete an agent session
beta.agents.sessions.delete(session_id) -> AgentSessionDeleted { id, deleted, object }
DELETE/agents/sessions/{session_id}
List agent sessions
beta.agents.sessions.list(**kwargs) -> CursorPage<AgentSession { id, agent, created_at, 9 more } >
GET/agents/sessions
Retrieve an agent session
beta.agents.sessions.retrieve(session_id) -> AgentSession { id, agent, created_at, 9 more }
GET/agents/sessions/{session_id}
Update an agent session
beta.agents.sessions.update(session_id, **kwargs) -> AgentSession { id, agent, created_at, 9 more }
POST/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content
beta.agents.sessions.artifacts.content(artifact_id, **kwargs) -> StringIO
GET/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
beta.agents.sessions.artifacts.delete(artifact_id, **kwargs) -> SessionArtifactDeleted { id, deleted, object }
DELETE/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
beta.agents.sessions.artifacts.list(session_id, **kwargs) -> CursorPage<SessionArtifact { id, created_at, environment_id, 5 more } >
GET/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
beta.agents.sessions.artifacts.retrieve(artifact_id, **kwargs) -> SessionArtifact { id, created_at, environment_id, 5 more }
GET/agents/sessions/{session_id}/artifacts/{artifact_id}
ModelsExpand Collapse
class SessionArtifact { id, created_at, environment_id, 5 more }

An immutable file published by a completed hosted session turn.

class SessionArtifactDeleted { id, deleted, object }

Confirmation that an immutable session artifact was deleted.

AgentsSessionsEvents

Create agent session input events
beta.agents.sessions.events.create(session_id, **kwargs) -> void
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) -> CursorPage<AgentSessionItem>
GET/agents/sessions/{session_id}/items

AgentsSessionsSubagents

List session subagents
beta.agents.sessions.subagents.list(session_id, **kwargs) -> CursorPage<Subagent { id, closed_at, instructions, 6 more } >
GET/agents/sessions/{session_id}/subagents
Retrieve a session subagent
beta.agents.sessions.subagents.retrieve(subagent_id, **kwargs) -> Subagent { id, closed_at, instructions, 6 more }
GET/agents/sessions/{session_id}/subagents/{subagent_id}

AgentsSessionsSubagentsItems

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

AgentsSessionsSubagentsTurns

List subagent turns
beta.agents.sessions.subagents.turns.list(subagent_id, **kwargs) -> CursorPage<Turn { id, agent_id, completed_at, 8 more } >
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
beta.agents.sessions.subagents.turns.retrieve(turn_id, **kwargs) -> Turn { id, agent_id, completed_at, 8 more }
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) -> CursorPage<AgentSessionItem>
GET/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items

AgentsSessionsTurns

List agent session turns
beta.agents.sessions.turns.list(session_id, **kwargs) -> CursorPage<Turn { id, agent_id, completed_at, 8 more } >
GET/agents/sessions/{session_id}/turns
Retrieve an agent session turn
beta.agents.sessions.turns.retrieve(turn_id, **kwargs) -> Turn { id, agent_id, completed_at, 8 more }
GET/agents/sessions/{session_id}/turns/{turn_id}
ModelsExpand Collapse
class Turn { id, agent_id, completed_at, 8 more }

The canonical public representation of a session turn.

AgentsVaults

Create a vault
beta.agents.vaults.create(**kwargs) -> Vault { id, created_at, metadata, 2 more }
POST/vaults
Delete a vault
beta.agents.vaults.delete(vault_id) -> VaultDeleted { id, deleted, object }
DELETE/vaults/{vault_id}
List vaults
beta.agents.vaults.list(**kwargs) -> CursorPage<Vault { id, created_at, metadata, 2 more } >
GET/vaults
Retrieve a vault
beta.agents.vaults.retrieve(vault_id) -> Vault { id, created_at, metadata, 2 more }
GET/vaults/{vault_id}
ModelsExpand Collapse
class Vault { id, created_at, metadata, 2 more }

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

class VaultDeleted { id, deleted, object }

Confirmation that a vault was deleted.

VaultStatus = :active | :archived

Whether a vault or credential is active or archived.

VaultStatusFilter = VaultStatus | Array[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 { id, auth, created_at, 4 more }
POST/vaults/{vault_id}/credentials
Delete a vault credential
beta.agents.vaults.credentials.delete(credential_id, **kwargs) -> CredentialDeleted { id, deleted, object }
DELETE/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
beta.agents.vaults.credentials.list(vault_id, **kwargs) -> CursorPage<Credential { id, auth, created_at, 4 more } >
GET/vaults/{vault_id}/credentials
Retrieve a vault credential
beta.agents.vaults.credentials.retrieve(credential_id, **kwargs) -> Credential { id, auth, created_at, 4 more }
GET/vaults/{vault_id}/credentials/{credential_id}
Rotate a vault credential
beta.agents.vaults.credentials.update(credential_id, **kwargs) -> Credential { id, auth, created_at, 4 more }
POST/vaults/{vault_id}/credentials/{credential_id}
ModelsExpand Collapse
class Credential { id, auth, created_at, 4 more }

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

CredentialAuth = McpOauth{ expires_at, mcp_server_url, refresh, type} | StaticBearer{ mcp_server_url, type} | EnvironmentVariable{ networking, secret_name, type}

The authentication configuration of a vault credential, excluding secrets.

CredentialAuthCreateParam = McpOauth{ access_token, mcp_server_url, type, 2 more} | StaticBearer{ token, mcp_server_url, type} | 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} | StaticBearer{ token, type} | EnvironmentVariable{ secret_value, type}

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

class CredentialDeleted { id, deleted, object }

Confirmation that a vault credential was deleted.

McpOauthTokenEndpointAuth = None{ type} | ClientSecretBasic{ type} | ClientSecretPost{ type}

The client authentication method used for OAuth token refresh.

McpOauthTokenEndpointAuthCreateParam = None{ type} | ClientSecretBasic{ client_secret, type} | ClientSecretPost{ client_secret, type}

Client authentication credentials for OAuth token refresh.

McpOauthTokenEndpointAuthRotateParam = ClientSecretBasic{ type, client_secret} | ClientSecretPost{ type, client_secret}

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