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
client.beta.agents.create(body, options?): Agent { id, created_at, instructions, 12 more }
POST
/agents
Delete an agent
client.beta.agents.delete(agentID, options?): AgentDeleted { id, deleted, object }
DELETE
/agents/{agent_id}
List agents
client.beta.agents.list(query?, options?): CursorPage<Agent { id, created_at, instructions, 12 more } >
GET
/agents
Retrieve an agent
client.beta.agents.retrieve(agentID, options?): Agent { id, created_at, instructions, 12 more }
GET
/agents/{agent_id}
Update an agent
client.beta.agents.update(agentID, body?, options?): Agent { id, created_at, instructions, 12 more }
POST
/agents/{agent_id}
Models
Agent { id, created_at, instructions, 12 more }

A reusable agent scoped to the caller’s project.

AgentBrowserAuthenticationCancelParam { action, type }
AgentBrowserAuthenticationSubmitParam { action, fields, type, selected_option }
AgentBrowserOriginAccessParam { decision, type }
AgentCloseSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

A request to close a subagent.

AgentCommandExecutionItem { id, command, cwd, 6 more }

A command execution produced by the agent.

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

A plaintext or encrypted content part exchanged between agents.

AgentCreateSubagentCallItem { id, agent_id, content, 5 more }

A request to spawn a subagent.

AgentDeleted { id, deleted, object }

A deleted reusable agent.

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.

  • in_progress - The call is in progress.
  • completed - The call completed successfully.
  • failed - The call failed.
  • incomplete - The call stopped before completing.
AgentInterruptSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

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

AgentMcpCallItem { id, arguments, error, 6 more }

A call to a tool on an MCP server.

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 } | 11 more

An output item produced by an agent.

AgentOutputItemStatus = "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.
AgentReasoning { effort, summary }

The reasoning configuration used by an agent.

AgentReasoningItem { id, status, summary, 2 more }

A reasoning item produced by the agent.

AgentReasoningParam { effort, summary }

Reasoning configuration for the agent.

AgentResumeSubagentCallItem { id, recipient_agent_id, sender_agent_id, 3 more }

A request to resume a subagent.

AgentSendSubagentInputCallItem { id, content, recipient_agent_id, 4 more }

A request to send input to another agent.

AgentSession { id, agent, created_at, 11 more }

A Managed Agents session.

AgentSessionAssistantMessage { id, content, phase, 4 more }

An assistant message produced by the agent.

AgentSessionCreatedEvent { event_id, session, type }

Emitted when a session is created.

AgentSessionDeleted { id, deleted, object }

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

AgentSessionEnvironmentConnectedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment connects.

AgentSessionEnvironmentDisconnectedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment disconnects.

AgentSessionEnvironmentExpiredEvent { environment, event_id, session_id, 2 more }

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

AgentSessionEnvironmentFailedEvent { environment, event_id, session_id, 2 more }

Emitted when a session environment fails.

AgentSessionEnvironmentPendingEvent { environment, event_id, session_id, 2 more }

Emitted while a session environment is being prepared.

AgentSessionEnvironmentReadyEvent { environment, event_id, session_id, 2 more }

Emitted when a hosted session environment is ready to connect.

AgentSessionEnvironmentResetEvent { environment_id, event_id, reset_count, 3 more }

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

AgentSessionEnvironmentState { id, error, status, type }

The current state of a session environment.

AgentSessionEnvironmentSuspendedEvent { environment, event_id, session_id, 2 more }

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

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 } | AgentSessionEnvironmentSuspendedEvent { environment, event_id, session_id, 2 more } | 30 more

An event emitted by a Managed Agents session.

AgentSessionFailedEvent { event_id, session, type }

Emitted when a session fails.

AgentSessionIdleEvent { event_id, session, type }

Emitted when a session becomes idle.

AgentSessionInProgressEvent { event_id, session, type }

Emitted when a session starts processing a turn.

AgentSessionInputMessageParam { content, role, type }

A user message submitted to a session.

AgentSessionInputParam = SessionInputParamAgentSessionInputComputerUseApprovalRequestResult { request_id, response, type } | SessionInputParamAgentSessionInputMessage { input, type } | SessionInputParamAgentSessionInputCancel { type } | SessionInputParamAgentSessionInputToolResult { 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 } | 14 more

An item associated with a session turn.

AgentSessionMessage { id, content, phase, 4 more }

A user or assistant message recorded in a session.

AgentSessionMessageContent = MessageContentResourceInputText { text, type } | MessageContentResourceInputImage { image_url, type } | MessageContentResourceOutputText { text, type }

A content part in a session message.

AgentSessionRequiresActionEvent { event_id, session, type }

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

AgentSessionSubagentActiveEvent { event_id, subagent, type }

Emitted when a closed subagent successfully resumes.

AgentSessionSubagentClosedEvent { event_id, subagent, type }

Emitted when a subagent is closed.

AgentSessionSubagentCreatedEvent { event_id, subagent, type }

Emitted when a subagent is created.

AgentSessionTurnCancelledEvent { event_id, session_id, turn, 3 more }

Emitted when a turn is cancelled.

AgentSessionTurnCompletedEvent { event_id, session_id, turn, 3 more }

Emitted when a turn completes.

AgentSessionTurnContentPartAddedEvent { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is added.

AgentSessionTurnContentPartDoneEvent { content_index, event_id, item_id, 5 more }

Emitted when an output content part is complete.

AgentSessionTurnCreatedEvent { event_id, session_id, turn, 2 more }

Emitted when a turn is created.

AgentSessionTurnFailedEvent { event_id, session_id, turn, 3 more }

Emitted when a turn fails.

AgentSessionTurnInProgressEvent { event_id, session_id, turn, 2 more }

Emitted when a turn starts running.

AgentSessionTurnItemAddedEvent { event_id, item, output_index, 3 more }

Emitted when an item is added to a turn.

AgentSessionTurnItemDoneEvent { event_id, item, output_index, 3 more }

Emitted when an output item is complete.

AgentSessionTurnOutputTextDeltaEvent { content_index, delta, event_id, 5 more }

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

AgentSessionTurnOutputTextDoneEvent { content_index, event_id, item_id, 5 more }

Emitted when an output text content part is complete.

AgentSessionTurnReasoningSummaryPartAddedEvent { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is added.

AgentSessionTurnReasoningSummaryPartDoneEvent { event_id, item_id, output_index, 6 more }

Emitted when a reasoning summary part is complete.

AgentSessionTurnReasoningSummaryTextDeltaEvent { delta, event_id, item_id, 5 more }

Emitted when text is appended to a reasoning summary.

AgentSessionTurnReasoningSummaryTextDoneEvent { event_id, item_id, output_index, 5 more }

Emitted when a reasoning summary content part is complete.

AgentText { format, verbosity }

The text configuration used by an agent.

AgentTextParam { format, verbosity }

Configuration for text generated by the agent.

AgentTool = AgentToolResourceFunction { defer_loading, description, name, 2 more } | AgentToolResourceProgrammaticToolCalling { enabled, type } | AgentToolResourceMcp { allowed_tools, connection_origin, credential_id, 5 more } | 3 more

A tool available to the agent.

AgentToolParam = AgentToolConfigParamFunction { description, name, parameters, 2 more } | AgentToolConfigParamToolSearch { type } | AgentToolConfigParamProgrammaticToolCalling { type, enabled } | 4 more

A tool available to the agent.

AgentWaitForSubagentsCallItem { id, recipient_agent_ids, sender_agent_id, 3 more }

A request to wait for one or more subagents.

AgentWebSearchCallItem { id, action, status, 2 more }

A web search call produced by the agent.

Environment = EnvironmentResourceNone { type } | EnvironmentResourceOpenAIHosted { id, capability_directories, files, 7 more } | EnvironmentResourceSelfHosted { id, capability_directories, remote_url, 2 more }

The execution environment for a session.

EnvironmentParam = EnvironmentParamNone { type } | EnvironmentParamOpenAIHosted { type, capability_directories, container_size, 10 more } | EnvironmentParamSelfHosted { type, workspace_directory, capability_directories }

The execution environment and optional reusable template for a session.

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

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

HostedEnvironmentFileID { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

HostedEnvironmentFileParam = HostedEnvironmentFileParamFileID { file_id, path, type } | HostedEnvironmentFileParamInline { data, path, type }

A file materialized in an OpenAI-hosted execution environment.

HostedPlugin { description, name, type }

A plugin installed from an inline ZIP archive.

HostedPluginParam { description, name, source, type }

Supplies a plugin ZIP directly in the session request.

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

A skill installed in an OpenAI-hosted environment.

HostedSkillParam = HostedSkillParamSkillReference { skill_id, type, version } | HostedSkillParamInline { description, name, source, type }

A skill installed in an OpenAI-hosted environment.

HostedSkillReference { description, name, skill_id, 2 more }

A skill installed from the Skills API.

InlineCapabilitySourceParam { data, media_type, type }

Provides ZIP bytes encoded with standard base64.

InputContent = InputContentResourceInputText { text, type } | InputContentResourceInputImage { image_url, type }

User-provided content recorded in a session item.

InputContentParam = InputContentParamInputText { text, type } | InputContentParamInputImage { image_url, type }

Content included in an input message.

McpTransport = McpTransportResourceHTTP { server_url, type } | McpTransportResourceStdio { args, command, cwd, 2 more }

The transport used to connect to an MCP server.

McpTransportParam = McpTransportConfigParamHTTP { server_url, type, authorization, headers } | McpTransportConfigParamStdio { command, cwd, type, 3 more }

The transport used to connect to an MCP server.

MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

MultiAgentConfigParam { enabled, max_concurrent_subagents }

Explicit configuration for creating and coordinating subagents.

OutputText { text, type }

A text content part produced by the agent.

PersistedAgentTool = PersistedAgentToolResourceFunction { defer_loading, description, name, 2 more } | PersistedAgentToolResourceToolSearch { type } | PersistedAgentToolResourceProgrammaticToolCalling { enabled, type } | 4 more

A credential-free tool available to a reusable agent.

PersistedAgentToolParam = PersistedAgentToolConfigParamFunction { description, name, parameters, 2 more } | PersistedAgentToolConfigParamToolSearch { type } | PersistedAgentToolConfigParamProgrammaticToolCalling { type, enabled } | 4 more

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

PersistedMcpTransport = PersistedMcpTransportResourceHTTP { headers, server_url, type } | PersistedMcpTransportResourceStdio { args, command, cwd, 2 more }

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

PersistedMcpTransportParam = PersistedMcpTransportConfigParamHTTP { server_url, type, headers } | PersistedMcpTransportConfigParamStdio { command, cwd, type, 2 more }

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

SessionError { code, message, param, type }

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

SessionTurnError { code, message }

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

SetupCommandParam { command, cwd }

A confidential setup command executed before the hosted agent starts.

Subagent { id, closed_at, instructions, 6 more }

A subagent created within a session.

SummaryText { text, type }

A reasoning summary content part.

TextFormat = TextFormatResourceText { type } | TextFormatResourceJSONSchema { schema, type }

The effective output format for generated text.

TextFormatParam = TextFormatParamText { type } | TextFormatParamJSONSchema { schema, type }

The output format for generated text.

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 = WebSearchActionResourceSearch { queries, query, type } | WebSearchActionResourceOpenPage { type, url } | WebSearchActionResourceFindInPage { pattern, type, url } | WebSearchActionResourceOther { type }

An action performed by the web search tool.

AgentsAutomations

Create an automation
client.beta.agents.automations.create(body, options?): Automation
POST
/agents/automations
Delete an automation
client.beta.agents.automations.delete(automationID, options?): AutomationDeleted { id, deleted, object }
DELETE
/agents/automations/{automation_id}
List automations
client.beta.agents.automations.list(query?, options?): CursorPage<Automation>
GET
/agents/automations
Pause an automation
client.beta.agents.automations.pause(automationID, options?): Automation
POST
/agents/automations/{automation_id}/pause
Resume an automation
client.beta.agents.automations.resume(automationID, options?): Automation
POST
/agents/automations/{automation_id}/resume
Get an automation
client.beta.agents.automations.retrieve(automationID, options?): Automation
GET
/agents/automations/{automation_id}
Update an automation
client.beta.agents.automations.update(automationID, body, options?): Automation
POST
/agents/automations/{automation_id}
Models
Automation = PeriodicAutomation { id, created_at, created_by, 8 more } | OneTimeAutomation { id, created_at, created_by, 7 more }

A saved automation and its schedule.

AutomationAgentConfig { instructions, model, multi_agent, 6 more }

Inline agent configuration without a generated session-local identity.

AutomationCreatedBy = AutomationCreatedByResourceDeveloper { type } | AutomationCreatedByResourceAgent { session_id, tool_call_id, type }

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

AutomationDeleted { id, deleted, object }
AutomationEnvironment = AutomationEnvironmentResourceNone { type } | AutomationEnvironmentResourceOpenAIHosted { capability_directories, container_size, desktop, 8 more } | AutomationEnvironmentResourceSelfHosted { capability_directories, environment_id, type, workspace_directory }

Environment selection saved before an invocation creates its session.

AutomationTarget = AutomationTargetResourceNewSession { agent, agent_id, environment, 4 more } | AutomationTargetResourceExistingSession { instructions, session_id, type }

Saved target configuration, excluding confidential request-only values.

AutomationTargetParam = AutomationTargetParamNewSession { environment, input, type, 4 more } | AutomationTargetParamExistingSession { instructions, session_id, type }

The session an automation invocation targets.

OneTimeAutomation { id, created_at, created_by, 7 more }

Fields shared by periodic and one-time automations.

PeriodicAutomation { id, created_at, created_by, 8 more }

Fields shared by periodic and one-time automations.

AgentsAutomationsInvocations

Invoke an automation
client.beta.agents.automations.invocations.create(automationID, options?): AutomationInvocation { id, automation_id, created_at, 7 more }
POST
/agents/automations/{automation_id}/invocations
List automation invocations
client.beta.agents.automations.invocations.list(automationID, query?, options?): CursorPage<AutomationInvocation { id, automation_id, created_at, 7 more } >
GET
/agents/automations/{automation_id}/invocations
Get an automation invocation
client.beta.agents.automations.invocations.retrieve(invocationID, params, options?): AutomationInvocation { id, automation_id, created_at, 7 more }
GET
/agents/automations/{automation_id}/invocations/{invocation_id}
Models
AutomationInvocation { id, automation_id, created_at, 7 more }

One attempted delivery by an automation.

AutomationInvocationSource = AutomationInvocationSourceResourceManual { type } | AutomationInvocationSourceResourceAutomation { automation, type }

AgentsEnvironments

Create an agent environment
client.beta.agents.environments.create(params, options?): EnvironmentInfo { id, files, object, 4 more }
POST
/agents/environments
List agent environments
client.beta.agents.environments.list(query?, options?): CursorPage<EnvironmentInfo { id, files, object, 4 more } >
GET
/agents/environments
Retrieve an agent environment
client.beta.agents.environments.retrieve(environmentID, options?): EnvironmentInfo { id, files, object, 4 more }
GET
/agents/environments/{environment_id}
Models
EnvironmentInfo { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

AgentsEnvironmentsFiles

Write an agent environment file
client.beta.agents.environments.files.create(environmentID, body, options?): EnvironmentFile { environment_id, object, path, size_bytes }
POST
/agents/environments/{environment_id}/files
List agent environment files
client.beta.agents.environments.files.list(environmentID, query?, options?): TokenPage<EnvironmentFile { environment_id, object, path, size_bytes } >
GET
/agents/environments/{environment_id}/files
Models
EnvironmentFile { environment_id, object, path, size_bytes }

A live file in an execution environment.

AgentsEnvironmentsTemplates

Create an agent environment template
client.beta.agents.environments.templates.create(body?, options?): EnvironmentTemplate { id, capability_directories, created_at, 9 more }
POST
/agents/environments/templates
Delete an agent environment template
client.beta.agents.environments.templates.delete(environmentTemplateID, options?): EnvironmentTemplateDeleted { id, deleted, object }
DELETE
/agents/environments/templates/{environment_template_id}
List agent environment templates
client.beta.agents.environments.templates.list(query?, options?): CursorPage<EnvironmentTemplate { id, capability_directories, created_at, 9 more } >
GET
/agents/environments/templates
Retrieve an agent environment template
client.beta.agents.environments.templates.retrieve(environmentTemplateID, options?): EnvironmentTemplate { id, capability_directories, created_at, 9 more }
GET
/agents/environments/templates/{environment_template_id}
Update an agent environment template
client.beta.agents.environments.templates.update(environmentTemplateID, body?, options?): EnvironmentTemplate { id, capability_directories, created_at, 9 more }
POST
/agents/environments/templates/{environment_template_id}
Models
EnvironmentTemplate { id, capability_directories, created_at, 9 more }

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

EnvironmentTemplateDeleted { id, deleted, object }

A deleted reusable environment template.

AgentsSessions

Create an agent session
client.beta.agents.sessions.create(body, options?): AgentSession { id, agent, created_at, 11 more } | Stream<AgentSessionEvent>
POST
/agents/sessions
Delete an agent session
client.beta.agents.sessions.delete(sessionID, options?): AgentSessionDeleted { id, deleted, object }
DELETE
/agents/sessions/{session_id}
List agent sessions
client.beta.agents.sessions.list(query?, options?): CursorPage<AgentSession { id, agent, created_at, 11 more } >
GET
/agents/sessions
Retrieve an agent session
client.beta.agents.sessions.retrieve(sessionID, options?): AgentSession { id, agent, created_at, 11 more }
GET
/agents/sessions/{session_id}
Update an agent session
client.beta.agents.sessions.update(sessionID, body?, options?): AgentSession { id, agent, created_at, 11 more }
POST
/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content
client.beta.agents.sessions.artifacts.content(artifactID, params, options?): Response
GET
/agents/sessions/{session_id}/artifacts/{artifact_id}/content
Delete an agent session artifact
client.beta.agents.sessions.artifacts.delete(artifactID, params, options?): SessionArtifactDeleted { id, deleted, object }
DELETE
/agents/sessions/{session_id}/artifacts/{artifact_id}
List agent session artifacts
client.beta.agents.sessions.artifacts.list(sessionID, query?, options?): CursorPage<SessionArtifact { id, created_at, environment_id, 5 more } >
GET
/agents/sessions/{session_id}/artifacts
Retrieve an agent session artifact
client.beta.agents.sessions.artifacts.retrieve(artifactID, params, options?): SessionArtifact { id, created_at, environment_id, 5 more }
GET
/agents/sessions/{session_id}/artifacts/{artifact_id}
Models
SessionArtifact { id, created_at, environment_id, 5 more }

An immutable file published by a completed hosted session turn.

SessionArtifactDeleted { id, deleted, object }

Confirmation that an immutable session artifact was deleted.

AgentsSessionsEvents

Create agent session input events
client.beta.agents.sessions.events.create(sessionID, params, options?): void
POST
/agents/sessions/{session_id}/events
Stream agent session events
client.beta.agents.sessions.events.stream(sessionID, options?): AgentSessionEvent | Stream<AgentSessionEvent>
GET
/agents/sessions/{session_id}/events

AgentsSessionsItems

List agent session items
client.beta.agents.sessions.items.list(sessionID, query?, options?): CursorPage<AgentSessionItem>
GET
/agents/sessions/{session_id}/items

AgentsSessionsSubagents

List session subagents
client.beta.agents.sessions.subagents.list(sessionID, query?, options?): CursorPage<Subagent { id, closed_at, instructions, 6 more } >
GET
/agents/sessions/{session_id}/subagents
Retrieve a session subagent
client.beta.agents.sessions.subagents.retrieve(subagentID, params, options?): Subagent { id, closed_at, instructions, 6 more }
GET
/agents/sessions/{session_id}/subagents/{subagent_id}

AgentsSessionsSubagentsItems

List subagent items
client.beta.agents.sessions.subagents.items.list(subagentID, params, options?): CursorPage<AgentSessionItem>
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/items

AgentsSessionsSubagentsTurns

List subagent turns
client.beta.agents.sessions.subagents.turns.list(subagentID, params, options?): CursorPage<Turn { id, agent_id, completed_at, 8 more } >
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns
Retrieve a subagent turn
client.beta.agents.sessions.subagents.turns.retrieve(turnID, params, options?): Turn { id, agent_id, completed_at, 8 more }
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}

AgentsSessionsSubagentsTurnsItems

List subagent turn items
client.beta.agents.sessions.subagents.turns.items.list(turnID, params, options?): CursorPage<AgentSessionItem>
GET
/agents/sessions/{session_id}/subagents/{subagent_id}/turns/{turn_id}/items

AgentsSessionsTraces

List agent session traces
client.beta.agents.sessions.traces.list(sessionID, query?, options?): CursorPage<SessionTrace { id, created_at, object, 2 more } >
GET
/agents/sessions/{session_id}/traces
Models
SessionTrace { id, created_at, object, 2 more }

AgentsSessionsTurns

List agent session turns
client.beta.agents.sessions.turns.list(sessionID, query?, options?): CursorPage<Turn { id, agent_id, completed_at, 8 more } >
GET
/agents/sessions/{session_id}/turns
Retrieve an agent session turn
client.beta.agents.sessions.turns.retrieve(turnID, params, options?): Turn { id, agent_id, completed_at, 8 more }
GET
/agents/sessions/{session_id}/turns/{turn_id}
Models
Turn { id, agent_id, completed_at, 8 more }

The canonical public representation of a session turn.

AgentsSessionsTurnsItems

List agent session turn items
client.beta.agents.sessions.turns.items.list(turnID, params, options?): ConversationCursorPage<AgentSessionItem>
GET
/agents/sessions/{session_id}/turns/{turn_id}/items

AgentsVaults

Create a vault
client.beta.agents.vaults.create(body?, options?): Vault { id, created_at, metadata, 2 more }
POST
/vaults
Delete a vault
client.beta.agents.vaults.delete(vaultID, options?): VaultDeleted { id, deleted, object }
DELETE
/vaults/{vault_id}
List vaults
client.beta.agents.vaults.list(query?, options?): CursorPage<Vault { id, created_at, metadata, 2 more } >
GET
/vaults
Retrieve a vault
client.beta.agents.vaults.retrieve(vaultID, options?): Vault { id, created_at, metadata, 2 more }
GET
/vaults/{vault_id}
Update a vault
client.beta.agents.vaults.update(vaultID, body, options?): Vault { id, created_at, metadata, 2 more }
POST
/vaults/{vault_id}
Models
Vault { id, created_at, metadata, 2 more }

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

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
client.beta.agents.vaults.credentials.create(vaultID, body, options?): Credential { id, auth, created_at, 5 more }
POST
/vaults/{vault_id}/credentials
Delete a vault credential
client.beta.agents.vaults.credentials.delete(credentialID, params, options?): CredentialDeleted { id, deleted, object }
DELETE
/vaults/{vault_id}/credentials/{credential_id}
List vault credentials
client.beta.agents.vaults.credentials.list(vaultID, query?, options?): CursorPage<Credential { id, auth, created_at, 5 more } >
GET
/vaults/{vault_id}/credentials
Retrieve a vault credential
client.beta.agents.vaults.credentials.retrieve(credentialID, params, options?): Credential { id, auth, created_at, 5 more }
GET
/vaults/{vault_id}/credentials/{credential_id}
Update a vault credential
client.beta.agents.vaults.credentials.update(credentialID, params, options?): Credential { id, auth, created_at, 5 more }
POST
/vaults/{vault_id}/credentials/{credential_id}
Models
Credential { id, auth, created_at, 5 more }

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

CredentialAuth = VaultCredentialAuthResourceMcpOauth { expires_at, mcp_server_url, refresh, type } | VaultCredentialAuthResourceStaticBearer { mcp_server_url, type } | VaultCredentialAuthResourceEnvironmentVariable { networking, secret_name, type }

The authentication configuration of a vault credential, excluding secrets.

CredentialAuthCreateParam = CreateVaultCredentialAuthParamMcpOauth { access_token, mcp_server_url, type, 2 more } | CreateVaultCredentialAuthParamStaticBearer { token, mcp_server_url, type } | CreateVaultCredentialAuthParamEnvironmentVariable { networking, secret_name, secret_value, type }

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

CredentialAuthRotateParam = RotateVaultCredentialAuthParamMcpOauth { type, access_token, expires_at, refresh } | RotateVaultCredentialAuthParamStaticBearer { token, type } | RotateVaultCredentialAuthParamEnvironmentVariable { secret_value, type }

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

CredentialDeleted { id, deleted, object }

Confirmation that a vault credential was deleted.

CredentialNetworking = VaultCredentialNetworkingResourceUnrestricted { type } | VaultCredentialNetworkingResourceLimited { allowed_hosts, type }

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

CredentialNetworkingParam = VaultCredentialNetworkingParamUnrestricted { type } | VaultCredentialNetworkingParamLimited { allowed_hosts, type }

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

McpOauthTokenEndpointAuth = McpOauthTokenEndpointAuthResourceNone { type } | McpOauthTokenEndpointAuthResourceClientSecretBasic { type } | McpOauthTokenEndpointAuthResourceClientSecretPost { type }

The client authentication method used for OAuth token refresh.

McpOauthTokenEndpointAuthCreateParam = CreateMcpOauthTokenEndpointAuthParamNone { type } | CreateMcpOauthTokenEndpointAuthParamClientSecretBasic { client_secret, type } | CreateMcpOauthTokenEndpointAuthParamClientSecretPost { client_secret, type }

Client authentication credentials for OAuth token refresh.

McpOauthTokenEndpointAuthRotateParam = RotateMcpOauthTokenEndpointAuthParamClientSecretBasic { type, client_secret } | RotateMcpOauthTokenEndpointAuthParamClientSecretPost { type, client_secret }

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