OpenAI API (unofficial showcase)
POST/agents/environments

Create an agent environment

Creates an OpenAI-hosted environment before creating a session. Requires access to the prewarming beta.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 2 body fields
Idempotency-Keystringoptional
Deduplicates creation for 24 hours within the authenticated organization, project, and creator. Retry the same JSON parameters with the same key to retrieve the original environment in its current state. Different parameters or an incomplete hosted creation return 409. Deleted environments are not recreated. After retention expires, the key may create a new environment. Without this header, each request creates a new environment.
environmentobjectrequired
The required hosting type and its configuration.
vault_idsarrayoptional
The IDs of up to 10 vaults made available to an OpenAI-hosted environment.

9 status codes
201The created OpenAI-hosted environment.
typestringrequired
Whether the environment is hosted by OpenAI or by the application.
Allowed:openai_hostedself_hosted
idstringrequired
The ID of the environment.
objectstringrequired
The object type. Always `agent.environment`.
Allowed:agent.environmentDefault:agent.environment
statusstringrequired
The current environment connection status.
Allowed:pendingreadyconnecteddisconnectedsuspendedexpiredfailed
filesarray<object>required
Files installed in the environment, without their contents.
skillsarray<object>required
Skills installed in the environment, without their archive contents.
pluginsarray<object>required
Plugins installed in the environment, without their archive contents.
400The request was invalid.
errorobjectrequired
The error returned by the API.
401Authentication or project context was missing.
errorobjectrequired
The error returned by the API.
403The API key lacks the required permission.
errorobjectrequired
The error returned by the API.
404The requested environment or referenced resource was not found.
errorobjectrequired
The error returned by the API.
409The request conflicted with the current environment state.
errorobjectrequired
The error returned by the API.
429The request exceeded a rate or capacity limit.
errorobjectrequired
The error returned by the API.
500An internal error occurred.
errorobjectrequired
The error returned by the API.
503The service is temporarily unavailable.
errorobjectrequired
The error returned by the API.

Error handling

A 400 is returned: The request was invalid. A 401 is returned: Authentication or project context was missing. A 403 is returned: The API key lacks the required permission. A 404 is returned: The requested environment or referenced resource was not found. A 409 is returned: The request conflicted with the current environment state. A 429 is returned: The request exceeded a rate or capacity limit. A 500 is returned: An internal error occurred. A 503 is returned: The service is temporarily unavailable.