API Reference

Beta

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Agents

Create an agent

client.Beta.Agents.New(ctx, body) (*Agent, error)

POST/agents

Delete an agent

client.Beta.Agents.Delete(ctx, agentID) (*AgentDeleted, error)

DELETE/agents/{agent_id}

List agents

client.Beta.Agents.List(ctx, query) (*CursorPage[Agent], error)

GET/agents

Retrieve an agent

client.Beta.Agents.Get(ctx, agentID) (*Agent, error)

GET/agents/{agent_id}

Update an agent

client.Beta.Agents.Update(ctx, agentID, body) (*Agent, error)

POST/agents/{agent_id}

ModelsExpand Collapse

type Agent struct{…}

A reusable agent scoped to the caller’s project.

type AgentCloseSubagentCallItem struct{…}

A request to close a subagent.

type AgentCommandExecutionItem struct{…}

A command execution produced by the agent.

type AgentContentUnion interface{…}

A plaintext or encrypted content part exchanged between agents.

type AgentCreateSubagentCallItem struct{…}

A request to spawn a subagent.

type AgentDeleted struct{…}

A deleted reusable agent.

type AgentFunctionCallItem struct{…}

A function call produced by the agent.

type AgentFunctionCallOutputUnion interface{…}

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

type AgentFunctionCallOutputParamUnionResp interface{…}

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

type AgentFunctionCallStatus string

The status of a tool call.

type AgentInterruptSubagentCallItem struct{…}

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

type AgentMcpCallItem struct{…}

A call to a tool on an MCP server.

type AgentOutputCommandExecutionOutputDeltaEvent struct{…}

Emitted when command execution produces an output delta.

type AgentOutputItemUnion interface{…}

An output item produced by an agent.

type AgentOutputItemStatus string

The status of an agent output item.

type AgentReasoning struct{…}

The reasoning configuration used by an agent.

type AgentReasoningItem struct{…}

A reasoning item produced by the agent.

type AgentReasoningParamResp struct{…}

Reasoning configuration for the agent.

type AgentResumeSubagentCallItem struct{…}

A request to resume a subagent.

type AgentSendSubagentInputCallItem struct{…}

A request to send input to another agent.

type AgentSession struct{…}

A Managed Agents session.

type AgentSessionAssistantMessage struct{…}

An assistant message produced by the agent.

type AgentSessionCreatedEvent struct{…}

Emitted when a session is created.

type AgentSessionDeleted struct{…}

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

type AgentSessionEnvironmentConnectedEvent struct{…}

Emitted when a session environment connects.

type AgentSessionEnvironmentDisconnectedEvent struct{…}

Emitted when a session environment disconnects.

type AgentSessionEnvironmentFailedEvent struct{…}

Emitted when a session environment fails.

type AgentSessionEnvironmentPendingEvent struct{…}

Emitted while a session environment is being prepared.

type AgentSessionEnvironmentReadyEvent struct{…}

Emitted when a hosted session environment is ready to connect.

type AgentSessionEnvironmentState struct{…}

The current state of a session environment.

type AgentSessionErrorEvent struct{…}

Emitted when a turn or session fails.

type AgentSessionEventUnion interface{…}

An event emitted by a Managed Agents session.

type AgentSessionFailedEvent struct{…}

Emitted when a session fails.

type AgentSessionIdleEvent struct{…}

Emitted when a session becomes idle.

type AgentSessionInProgressEvent struct{…}

Emitted when a session starts processing a turn.

type AgentSessionInputMessageParamResp struct{…}

A user message submitted to a session.

type AgentSessionInputParamUnionResp interface{…}

Input submitted to an existing session.

type AgentSessionItemUnion interface{…}

An item associated with a session turn.

type AgentSessionMessage struct{…}

A user or assistant message recorded in a session.

type AgentSessionMessageContentUnion interface{…}

A content part in a session message.

type AgentSessionRequiresActionEvent struct{…}

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

type AgentSessionSubagentActiveEvent struct{…}

Emitted when a closed subagent successfully resumes.

type AgentSessionSubagentClosedEvent struct{…}

Emitted when a subagent is closed.

type AgentSessionSubagentCreatedEvent struct{…}

Emitted when a subagent is created.

type AgentSessionTurnCancelledEvent struct{…}

Emitted when a turn is cancelled.

type AgentSessionTurnCompletedEvent struct{…}

Emitted when a turn completes.

type AgentSessionTurnContentPartAddedEvent struct{…}

Emitted when an output text content part is added.

type AgentSessionTurnContentPartDoneEvent struct{…}

Emitted when an output content part is complete.

type AgentSessionTurnCreatedEvent struct{…}

Emitted when a turn is created.

type AgentSessionTurnFailedEvent struct{…}

Emitted when a turn fails.

type AgentSessionTurnInProgressEvent struct{…}

Emitted when a turn starts running.

type AgentSessionTurnItemAddedEvent struct{…}

Emitted when an item is added to a turn.

type AgentSessionTurnItemDoneEvent struct{…}

Emitted when an output item is complete.

type AgentSessionTurnOutputTextDeltaEvent struct{…}

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

type AgentSessionTurnOutputTextDoneEvent struct{…}

Emitted when an output text content part is complete.

type AgentSessionTurnReasoningSummaryPartAddedEvent struct{…}

Emitted when a reasoning summary content part is added.

type AgentSessionTurnReasoningSummaryPartDoneEvent struct{…}

Emitted when a reasoning summary part is complete.

type AgentSessionTurnReasoningSummaryTextDeltaEvent struct{…}

Emitted when text is appended to a reasoning summary.

type AgentSessionTurnReasoningSummaryTextDoneEvent struct{…}

Emitted when a reasoning summary content part is complete.

type AgentText struct{…}

The text configuration used by an agent.

type AgentTextParamResp struct{…}

Configuration for text generated by the agent.

type AgentToolUnion interface{…}

A tool available to the agent.

type AgentToolParamUnionResp interface{…}

A tool available to the agent.

type AgentWaitForSubagentsCallItem struct{…}

A request to wait for one or more subagents.

type AgentWebSearchCallItem struct{…}

A web search call produced by the agent.

type EnvironmentUnion interface{…}

The execution environment for a session.

type EnvironmentParamUnionResp interface{…}

The execution environment and optional reusable template for a session.

type HostedEnvironmentFileUnion interface{…}

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

type HostedEnvironmentFileID struct{…}

A file copied from the OpenAI Files API.

type HostedEnvironmentFileParamUnionResp interface{…}

A file materialized in an OpenAI-hosted execution environment.

type HostedPlugin struct{…}

A plugin installed from an inline ZIP archive.

type HostedPluginParamResp struct{…}

Supplies a plugin ZIP directly in the session request.

type HostedSkillUnion interface{…}

A skill installed in an OpenAI-hosted environment.

type HostedSkillParamUnionResp interface{…}

A skill installed in an OpenAI-hosted environment.

type HostedSkillReference struct{…}

A skill installed from the Skills API.

type InlineCapabilitySourceParamResp struct{…}

Provides ZIP bytes encoded with standard base64.

type InputContentUnion interface{…}

User-provided content recorded in a session item.

type InputContentParamUnionResp interface{…}

Content included in an input message.

type McpTransportUnion interface{…}

The transport used to connect to an MCP server.

type McpTransportParamUnionResp interface{…}

The transport used to connect to an MCP server.

type MultiAgentConfig struct{…}

The resolved configuration for creating and coordinating subagents.

type MultiAgentConfigParamResp struct{…}

Explicit configuration for creating and coordinating subagents.

type OutputText struct{…}

A text content part produced by the agent.

type PersistedAgentToolUnion interface{…}

A credential-free tool available to a reusable agent.

type PersistedAgentToolParamUnionResp interface{…}

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

type PersistedMcpTransportUnion interface{…}

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

type PersistedMcpTransportParamUnionResp interface{…}

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

type SessionError struct{…}

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

type SessionTurnError struct{…}

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

type SetupCommandParamResp struct{…}

A confidential setup command executed before the hosted agent starts.

type Subagent struct{…}

A subagent created within a session.

type SummaryText struct{…}

A reasoning summary content part.

type TextFormatUnion interface{…}

The effective output format for generated text.

type TextFormatParamUnionResp interface{…}

The output format for generated text.

type TokenUsage struct{…}

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

type WebSearchActionUnion interface{…}

An action performed by the web search tool.

AgentsEnvironments

Retrieve an agent environment

client.Beta.Agents.Environments.Get(ctx, environmentID) (*EnvironmentInfo, error)

GET/agents/environments/{environment_id}

ModelsExpand Collapse

type EnvironmentInfo struct{…}

Safe metadata for a first-class execution environment.

AgentsEnvironmentsFiles

Create an agent environment file

client.Beta.Agents.Environments.Files.New(ctx, environmentID, body) (*EnvironmentFile, error)

POST/agents/environments/{environment_id}/files

List agent environment files

client.Beta.Agents.Environments.Files.List(ctx, environmentID, query) (*TokenPage[EnvironmentFile], error)

GET/agents/environments/{environment_id}/files

ModelsExpand Collapse

type EnvironmentFile struct{…}

A live file in an execution environment.

AgentsEnvironmentsTemplates

Create an agent environment template

client.Beta.Agents.Environments.Templates.New(ctx, body) (*EnvironmentTemplate, error)

POST/agents/environments/templates

Delete an agent environment template

client.Beta.Agents.Environments.Templates.Delete(ctx, environmentTemplateID) (*EnvironmentTemplateDeleted, error)

DELETE/agents/environments/templates/{environment_template_id}

List agent environment templates

client.Beta.Agents.Environments.Templates.List(ctx, query) (*CursorPage[EnvironmentTemplate], error)

GET/agents/environments/templates

Retrieve an agent environment template

client.Beta.Agents.Environments.Templates.Get(ctx, environmentTemplateID) (*EnvironmentTemplate, error)

GET/agents/environments/templates/{environment_template_id}

Update an agent environment template

client.Beta.Agents.Environments.Templates.Update(ctx, environmentTemplateID, body) (*EnvironmentTemplate, error)

POST/agents/environments/templates/{environment_template_id}

ModelsExpand Collapse

type EnvironmentTemplate struct{…}

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

type EnvironmentTemplateDeleted struct{…}

A deleted reusable environment template.

AgentsSessions

Create an agent session

client.Beta.Agents.Sessions.New(ctx, body) (*AgentSession, error)

POST/agents/sessions

Delete an agent session

client.Beta.Agents.Sessions.Delete(ctx, sessionID) (*AgentSessionDeleted, error)

DELETE/agents/sessions/{session_id}

List agent sessions

client.Beta.Agents.Sessions.List(ctx, query) (*CursorPage[AgentSession], error)

GET/agents/sessions

Retrieve an agent session

client.Beta.Agents.Sessions.Get(ctx, sessionID) (*AgentSession, error)

GET/agents/sessions/{session_id}

Update an agent session

client.Beta.Agents.Sessions.Update(ctx, sessionID, body) (*AgentSession, error)

POST/agents/sessions/{session_id}

AgentsSessionsArtifacts

Retrieve agent session artifact content

client.Beta.Agents.Sessions.Artifacts.Content(ctx, sessionID, artifactID) (*Response, error)

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

Delete an agent session artifact

client.Beta.Agents.Sessions.Artifacts.Delete(ctx, sessionID, artifactID) (*SessionArtifactDeleted, error)

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

List agent session artifacts

client.Beta.Agents.Sessions.Artifacts.List(ctx, sessionID, query) (*CursorPage[SessionArtifact], error)

GET/agents/sessions/{session_id}/artifacts

Retrieve an agent session artifact

client.Beta.Agents.Sessions.Artifacts.Get(ctx, sessionID, artifactID) (*SessionArtifact, error)

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

ModelsExpand Collapse

type SessionArtifact struct{…}

An immutable file published by a completed hosted session turn.

type SessionArtifactDeleted struct{…}

Confirmation that an immutable session artifact was deleted.

AgentsSessionsEvents

Create agent session input events

client.Beta.Agents.Sessions.Events.New(ctx, sessionID, params) error

POST/agents/sessions/{session_id}/events

Stream agent session events

client.Beta.Agents.Sessions.Events.Stream(ctx, sessionID) (*AgentSessionEventUnion, error)

GET/agents/sessions/{session_id}/events

AgentsSessionsItems

List agent session items

client.Beta.Agents.Sessions.Items.List(ctx, sessionID, query) (*CursorPage[AgentSessionItemUnion], error)

GET/agents/sessions/{session_id}/items

AgentsSessionsSubagents

List session subagents

client.Beta.Agents.Sessions.Subagents.List(ctx, sessionID, query) (*CursorPage[Subagent], error)

GET/agents/sessions/{session_id}/subagents

Retrieve a session subagent

client.Beta.Agents.Sessions.Subagents.Get(ctx, sessionID, subagentID) (*Subagent, error)

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

AgentsSessionsSubagentsItems

List subagent items

client.Beta.Agents.Sessions.Subagents.Items.List(ctx, sessionID, subagentID, query) (*CursorPage[AgentSessionItemUnion], error)

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

AgentsSessionsSubagentsTurns

List subagent turns

client.Beta.Agents.Sessions.Subagents.Turns.List(ctx, sessionID, subagentID, query) (*CursorPage[Turn], error)

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

Retrieve a subagent turn

client.Beta.Agents.Sessions.Subagents.Turns.Get(ctx, sessionID, subagentID, turnID) (*Turn, error)

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

AgentsSessionsSubagentsTurnsItems

List subagent turn items

client.Beta.Agents.Sessions.Subagents.Turns.Items.List(ctx, sessionID, subagentID, turnID, query) (*CursorPage[AgentSessionItemUnion], error)

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

AgentsSessionsTurns

List agent session turns

client.Beta.Agents.Sessions.Turns.List(ctx, sessionID, query) (*CursorPage[Turn], error)

GET/agents/sessions/{session_id}/turns

Retrieve an agent session turn

client.Beta.Agents.Sessions.Turns.Get(ctx, sessionID, turnID) (*Turn, error)

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

ModelsExpand Collapse

type Turn struct{…}

The canonical public representation of a session turn.

AgentsVaults

Create a vault

client.Beta.Agents.Vaults.New(ctx, body) (*Vault, error)

POST/vaults

Delete a vault

client.Beta.Agents.Vaults.Delete(ctx, vaultID) (*VaultDeleted, error)

DELETE/vaults/{vault_id}

List vaults

client.Beta.Agents.Vaults.List(ctx, query) (*CursorPage[Vault], error)

GET/vaults

Retrieve a vault

client.Beta.Agents.Vaults.Get(ctx, vaultID) (*Vault, error)

GET/vaults/{vault_id}

ModelsExpand Collapse

type Vault struct{…}

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

type VaultDeleted struct{…}

Confirmation that a vault was deleted.

type VaultStatus string

Whether a vault or credential is active or archived.

type VaultStatusFilterUnion interface{…}

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

AgentsVaultsCredentials

Create a vault credential

client.Beta.Agents.Vaults.Credentials.New(ctx, vaultID, body) (*Credential, error)

POST/vaults/{vault_id}/credentials

Delete a vault credential

client.Beta.Agents.Vaults.Credentials.Delete(ctx, vaultID, credentialID) (*CredentialDeleted, error)

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

List vault credentials

client.Beta.Agents.Vaults.Credentials.List(ctx, vaultID, query) (*CursorPage[Credential], error)

GET/vaults/{vault_id}/credentials

Retrieve a vault credential

client.Beta.Agents.Vaults.Credentials.Get(ctx, vaultID, credentialID) (*Credential, error)

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

Rotate a vault credential

client.Beta.Agents.Vaults.Credentials.Update(ctx, vaultID, credentialID, body) (*Credential, error)

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

ModelsExpand Collapse

type Credential struct{…}

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

type CredentialAuthUnion interface{…}

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

type CredentialAuthCreateParamUnionResp interface{…}

Authentication credentials for an MCP server used by agent tools.

type CredentialAuthRotateParamUnionResp interface{…}

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

type CredentialDeleted struct{…}

Confirmation that a vault credential was deleted.

type McpOAuthTokenEndpointAuthUnion interface{…}

The client authentication method used for OAuth token refresh.

type McpOAuthTokenEndpointAuthCreateParamUnionResp interface{…}

Client authentication credentials for OAuth token refresh.

type McpOAuthTokenEndpointAuthRotateParamUnionResp interface{…}

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