OpenAI API (unofficial showcase)
POST/agents/environments/{environment_id}/files

Write a file to an agent environment

Writes a file to a connected agent execution environment, using either inline base64 data or a file uploaded through the Files API. Choose the inline or file_id body variant and provide the absolute destination path; writing to an existing regular file at that path replaces it. Upload the file between turns and wait for success before starting the next turn.

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

1 parameter · 3 body fields
environment_idstringrequired
The ID of the agent environment to write the file to.

A file to materialize in the environment, supplied either as an uploaded Files API file or as standard-base64-encoded inline data.

typestringrequired
The type of the object. Always `file_id`.
Allowed:file_idDefault:file_id
file_idstringrequired
The ID of the uploaded file.
pathstringrequired
The absolute destination path inside `/workspace`.

9 status codes
201Returns the written environment file with its environment ID, absolute path, and size in bytes.
objectstringrequired
The object type. Always `agent.environment.file`.
Allowed:agent.environment.fileDefault:agent.environment.file
environment_idstringrequired
The ID of the environment containing this file.
pathstringrequired
The absolute file path inside the environment's workspace.
size_bytesintegerrequired
The file size in bytes.
400Returned when the request is invalid.
errorobjectrequired
The error returned by the API.
401Returned when authentication or project context is missing.
errorobjectrequired
The error returned by the API.
403Returned when the API key lacks the required permission.
errorobjectrequired
The error returned by the API.
404Returned when the requested session or event is not found.
errorobjectrequired
The error returned by the API.
409Returned when the request conflicts with the current session state.
errorobjectrequired
The error returned by the API.
429Returned when the Files API rate limit for your user has been exceeded.
errorobjectrequired
The error returned by the API.
500Returned when an internal error occurs.
errorobjectrequired
The error returned by the API.
503Returned when the service is temporarily unavailable.
errorobjectrequired
The error returned by the API.

Error handling

A 400 is returned when the request is invalid; a 401 when authentication or project context is missing; a 403 when the API key lacks the required permission; a 404 when the requested session or event is not found; and a 409 when the request conflicts with the current session state. A 429 indicates that the Files API rate limit for your user has been exceeded; a 500 indicates an internal error; and a 503 indicates that the service is temporarily unavailable. The body must match one of its two variants: type must be file_id with file_id and path, or inline with data and path.