---
title: "Write an agent environment file"
method: POST
path: "/agents/environments/{environment_id}/files"
tags: ["Agents"]
---

# Write an agent environment file

`POST /agents/environments/{environment_id}/files`

## Request

- Base URL: `https://api.openai.com/v1`
- URL: `https://api.openai.com/v1/agents/environments/{environment_id}/files`
- Auth: HTTP bearer

Copies inline bytes or a Files API file into a connected execution environment, replacing an existing regular file at the same path. Upload between turns and wait for success before starting the next turn. See [environment files](https://developers.openai.com/api/docs/guides/agents-api/environments/files).

## Path parameters

- `environment_id` string, required

## Request body

- 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 `201`

The written live environment file.

- EnvironmentFileResource: A live file in an execution environment.
  - `object` 'agent.environment.file', required: The object type. Always `agent.environment.file`.
  - `environment_id` string, required: The ID of the environment containing this file.
  - `path` string, required: The absolute file path inside the environment's workspace.
  - `size_bytes` integer, required: The file size in bytes.

## Other responses

- `400`: The request was invalid.
- `401`: Authentication or project context was missing.
- `403`: The API key lacks the required permission.
- `404`: The requested session or event was not found.
- `409`: The request conflicted with the current session state.
- `429`: The Files API rate limit for your user has been exceeded.
- `500`: An internal error occurred.
- `503`: The service is temporarily unavailable.

## Changes

- **2026-10-06** `81031e5704b1`: 1 info
  - added the non-success response with the status `429`
- **2026-10-05** `7f654af7f94f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/omnistack-sh/apis/openai-api/changes/agents/environments/:environment_id/files/post.md)

---

[API](https://skmtc.dev/omnistack-sh/apis/openai-api.md) - [All operations](https://skmtc.dev/omnistack-sh/apis/openai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnistack-sh/apis/openai-api/revisions/0a26f104d35f?raw)