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

Environments

Create an agent environment
POST/agents/environments
List agent environments
GET/agents/environments
Retrieve an agent environment
GET/agents/environments/{environment_id}
ModelsExpand Collapse
EnvironmentInfo object { id, files, object, 4 more }

Safe metadata for a first-class execution environment.

id: string

The ID of the environment.

minLength0
files: array of HostedEnvironmentFile

Files installed in the environment, without their contents.

One of the following:
HostedEnvironmentFileID object { id, file_id, path, 2 more }

A file copied from the OpenAI Files API.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "file_id"

The type of the object. Always file_id.

Inline object { id, path, size_bytes, type }

A file supplied inline when the session was created.

id: string

The session-scoped ID of the file in the execution environment.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded file size in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

object: "agent.environment"

The object type. Always agent.environment.

plugins: array of HostedPlugin { description, name, type }

Plugins installed in the environment, without their archive contents.

description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

skills: array of HostedSkill

Skills installed in the environment, without their archive contents.

One of the following:
HostedSkillReference object { description, name, skill_id, 2 more }

A skill installed from the Skills API.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string

The concrete skill version installed for this session.

minLength0
Inline object { description, name, type }

A skill installed from an inline ZIP archive.

description: string

The installed skill description.

minLength0
name: string

The installed skill name.

minLength0
type: "inline"

The type of the object. Always inline.

status: "pending" or "ready" or "connected" or 4 more

The current environment connection status.

One of the following:
"pending"
"ready"

Provisioning succeeded and the environment is available for attachment or use.

"connected"
"disconnected"
"suspended"

The sandbox is stopped and can be resumed from its private checkpoint.

"expired"
"failed"
type: "openai_hosted" or "self_hosted"

Whether the environment is hosted by OpenAI or by the application.

One of the following:
"openai_hosted"
"self_hosted"

EnvironmentsFiles

Create an agent environment file
POST/agents/environments/{environment_id}/files
List agent environment files
GET/agents/environments/{environment_id}/files
ModelsExpand Collapse
EnvironmentFile object { environment_id, object, path, size_bytes }

A live file in an execution environment.

environment_id: string

The ID of the environment containing this file.

minLength0
object: "agent.environment.file"

The object type. Always agent.environment.file.

path: string

The absolute file path inside the environment’s workspace.

minLength0
size_bytes: number

The file size in bytes.

formatint64
minimum0

EnvironmentsTemplates

Create an agent environment template
POST/agents/environments/templates
Delete an agent environment template
DELETE/agents/environments/templates/{environment_template_id}
List agent environment templates
GET/agents/environments/templates
Retrieve an agent environment template
GET/agents/environments/templates/{environment_template_id}
Update an agent environment template
POST/agents/environments/templates/{environment_template_id}
ModelsExpand Collapse
EnvironmentTemplate object { id, capability_directories, created_at, 9 more }

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

id: string

The ID of the reusable environment template.

minLength0
capability_directories: array of string

Directories that expose capabilities to the agent.

created_at: number

The Unix timestamp, in seconds, when the template was created.

formatint64
desktop: object { enabled }

Desktop configuration for each OpenAI-hosted environment.

enabled: boolean

Whether the environment provisions a desktop and browser proxy.

files: array of FileID { file_id, path, type } or Inline { path, size_bytes, type }

Safe file metadata, excluding contents and session-scoped file IDs.

One of the following:
FileID object { file_id, path, type }

A project-scoped Files API reference resolved separately for each session.

file_id: string

The ID of the uploaded file.

minLength0
path: string

The file’s absolute path inside the environment.

minLength0
type: "file_id"

The type of the object. Always file_id.

Inline object { path, size_bytes, type }

Metadata for confidential inline file contents.

path: string

The file’s absolute path inside the environment.

minLength0
size_bytes: number

The decoded size of the inline file in bytes.

formatint64
minimum0
type: "inline"

The type of the object. Always inline.

name: string or null

An optional human-readable display name for the template.

minLength0
network: object { access, allowed_domains }

Runtime network access for each OpenAI-hosted environment.

access: "enabled" or "disabled" or "restricted"

The environment’s network access mode.

One of the following:
"enabled"

Allows unrestricted network access.

"disabled"

Disables network access.

"restricted"

Applies the configured domain restrictions.

allowed_domains: array of string

Domains the environment may access when network access is restricted.

object: "agent.environment.template"

The object type. Always agent.environment.template.

packages: object { npm, python, system }

Packages installed in each fresh OpenAI-hosted environment.

npm: array of string

npm packages installed globally in the environment.

python: array of string

Python packages installed in the environment.

system: array of string

System packages installed in the environment.

plugins: array of HostedPlugin { description, name, type }

Safe plugin metadata, excluding inline archive contents.

description: string

The installed plugin description.

minLength0
name: string

The installed plugin name.

minLength0
type: "inline"

The type of the object. Always inline.

skills: array of SkillReference { skill_id, type, version } or Inline { description, name, type }

Safe skill metadata, preserving unresolved version selectors.

One of the following:
SkillReference object { skill_id, type, version }

A skill resolved afresh from the Skills API whenever a session starts.

skill_id: string

The referenced skill ID.

minLength0
type: "skill_reference"

The type of the object. Always skill_reference.

version: string or null

The requested version selector, including latest.

minLength0
Inline object { description, name, type }

Safe metadata for an inline skill archive.

description: string

The skill description declared in SKILL.md.

minLength0
name: string

The skill name declared in SKILL.md.

minLength0
type: "inline"

The type of the object. Always inline.

updated_at: number

The Unix timestamp, in seconds, when the template was last updated.

formatint64
EnvironmentTemplateDeleted object { id, deleted, object }

A deleted reusable environment template.

id: string

The ID of the deleted environment template.

minLength0
deleted: boolean

Whether the environment template was deleted. Always true.

object: "agent.environment.template.deleted"

The object type. Always agent.environment.template.deleted.