---
title: "Update an agent environment template"
method: POST
path: "/agents/environments/templates/{environment_template_id}"
tags: ["Agents"]
---

# Update an agent environment template

`POST /agents/environments/templates/{environment_template_id}`

Updates reusable environment configuration without returning confidential values. See [reusing a hosted setup](https://developers.openai.com/api/docs/guides/agents-api/tools#reuse-a-hosted-plugin-setup).

## Path parameters

- `environment_template_id` string, required

## Request body

- UpdateEnvironmentTemplateParams — Fields to replace on an existing reusable OpenAI-hosted environment template.
  - `name` string, nullable — A replacement human-readable display name, or `null` to clear the name.
  - `packages` EnvironmentPackagesParam — Packages to install in an OpenAI-hosted environment.
    - `python` string[], nullable — Python packages to install. Defaults to an empty list.
    - `system` string[], nullable — System packages to install. Defaults to an empty list.
    - `npm` string[], nullable — npm packages to install globally. Defaults to an empty list.
  - `setup_commands` SetupCommandParam[], nullable — Replacement confidential setup commands, never included in returned resources.
    - `command` string, required — The shell command to execute.
    - `cwd` string, nullable — The absolute working directory. Defaults to `/workspace`.
  - `network` NetworkPolicyParam — Network access for an OpenAI-hosted environment.
    - `access` 'enabled' | 'disabled' | 'restricted', required — The network access mode for an OpenAI-hosted environment.
    - `allowed_domains` string[], nullable — Domains the environment may access when network access is restricted.
  - `env` object, nullable — Replacement confidential environment values.
  - `capability_directories` string[], nullable — Directories that expose capabilities to the agent.
  - `skills` HostedSkillParam[], nullable — Replacement skill configuration installed for each new session.
    - union — A skill installed in an OpenAI-hosted environment.
      - object — References a skill uploaded through the Skills API.
        - `type` 'skill_reference', required — The type of the object. Always `skill_reference`.
        - `skill_id` string, required — The ID of the skill created through `/v1/skills`.
        - `version` string, nullable — The skill version, a positive integer or `latest`; omission selects the default.
      - object — Supplies a skill ZIP directly in the session request.
        - `type` 'inline', required — The type of the object. Always `inline`.
        - `name` string, required — The skill name declared in `SKILL.md`.
        - `description` string, required — The skill description declared in `SKILL.md`.
        - `source` InlineCapabilitySourceParam, required — Provides ZIP bytes encoded with standard base64.
          - `type` 'base64', required — The type of the object. Always `base64`.
          - `media_type` 'application/zip', required — The archive media type, always `application/zip`.
          - `data` string, required — Standard-base64 encoded ZIP archive bytes.
  - `plugins` HostedPluginParam[], nullable — Replacement plugin configuration installed for each new session.
    - `type` 'inline', required — The type of the object. Always `inline`.
    - `name` string, required — The plugin name declared in `.codex-plugin/plugin.json`.
    - `description` string, required — The plugin description declared in `.codex-plugin/plugin.json`.
    - `source` InlineCapabilitySourceParam, required — Provides ZIP bytes encoded with standard base64.
      - `type` 'base64', required — The type of the object. Always `base64`.
      - `media_type` 'application/zip', required — The archive media type, always `application/zip`.
      - `data` string, required — Standard-base64 encoded ZIP archive bytes.
  - `files` HostedEnvironmentFileParam[], nullable — Replacement file configuration materialized for each new session.
    - union — A file materialized in an OpenAI-hosted execution environment.
      - object — A file previously uploaded through the OpenAI Files API.
        - `type` 'file_id', required — The type of the object. Always `file_id`.
        - `file_id` string, required — The ID of the uploaded file.
        - `path` string, required — The absolute destination path inside `/workspace`.
      - object — A file supplied directly as standard-base64 data.
        - `type` 'inline', required — The type of the object. Always `inline`.
        - `data` string, required — The standard-base64-encoded file contents.
        - `path` string, required — The absolute destination path inside `/workspace`.

## Response `200`

The updated environment template.

- EnvironmentTemplateResource — Reusable configuration that provisions a fresh OpenAI-hosted environment for each session.
  - `id` string, required — The ID of the reusable environment template.
  - `name` string, nullable, required — An optional human-readable display name for the template.
  - `object` 'agent.environment.template', required — The object type. Always `agent.environment.template`.
  - `created_at` integer, required — The Unix timestamp, in seconds, when the template was created.
  - `updated_at` integer, required — The Unix timestamp, in seconds, when the template was last updated.
  - `packages` EnvironmentPackagesResource, required — Packages installed in an OpenAI-hosted environment.
    - `python` string[], required — Python packages installed in the environment.
    - `system` string[], required — System packages installed in the environment.
    - `npm` string[], required — npm packages installed globally in the environment.
  - `network` NetworkPolicyResource, required — Network access for an OpenAI-hosted environment.
    - `access` 'enabled' | 'disabled' | 'restricted', required — The network access mode for an OpenAI-hosted environment.
    - `allowed_domains` string[], required — Domains the environment may access when network access is restricted.
  - `capability_directories` string[], required — Directories that expose capabilities to the agent.
  - `skills` HostedTemplateSkillResource[], required — Safe skill metadata, preserving unresolved version selectors.
    - union — Safe metadata for a skill configured by an environment template.
      - object — A skill resolved afresh from the Skills API whenever a session starts.
        - `type` 'skill_reference', required — The type of the object. Always `skill_reference`.
        - `skill_id` string, required — The referenced skill ID.
        - `version` string, nullable, required — The requested version selector, including `latest`.
      - object — Safe metadata for an inline skill archive.
        - `type` 'inline', required — The type of the object. Always `inline`.
        - `name` string, required — The skill name declared in `SKILL.md`.
        - `description` string, required — The skill description declared in `SKILL.md`.
  - `plugins` HostedPluginResource[], required — Safe plugin metadata, excluding inline archive contents.
    - `type` 'inline', required — The type of the object. Always `inline`.
    - `name` string, required — The installed plugin name.
    - `description` string, required — The installed plugin description.
  - `files` HostedTemplateFileResource[], required — Safe file metadata, excluding contents and session-scoped file IDs.
    - union — Safe metadata for a file configured by an environment template.
      - object — A project-scoped Files API reference resolved separately for each session.
        - `type` 'file_id', required — The type of the object. Always `file_id`.
        - `file_id` string, required — The ID of the uploaded file.
        - `path` string, required — The file's absolute path inside the environment.
      - object — Metadata for confidential inline file contents.
        - `type` 'inline', required — The type of the object. Always `inline`.
        - `path` string, required — The file's absolute path inside the environment.
        - `size_bytes` integer, required — The decoded size of the inline file in bytes.

## Other responses

- `400` — The request was invalid.
- `401` — Authentication or project context was missing.
- `403` — The API key lacks the required management permission.
- `404` — The requested environment definition was not found.
- `409` — The request conflicted with the current environment state.
- `500` — An internal error occurred.
- `503` — The service is temporarily unavailable.

## Changes

- **2026-09-10** `f2dae1a9aced` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openai/apis/openapi/changes/agents/environments/templates/:environment_template_id/post.md)

---

[API](https://skmtc.dev/openai/apis/openapi.md) · [All operations](https://skmtc.dev/openai/apis/openapi/llms.txt) · [OpenAPI document](https://skmtc.dev/openai/apis/openapi/revisions/f44c092d9892?raw)