Skip to main content

Write an environment file

Write a source file in the current workspace to a path in a managed environment.

Endpoint

POST /agents/environments/{environment_id}/files Writes a source file to a /workspace/ path in the specified environment. A successful call returns 201 and environment file information. A successful write means the file is on disk; it does not mean the model has read it.

Path parameters

environment_id string (required)Environment ID, an environment in the current workspace

Request body

type string (required)File reference type, fixed as file_idfile_id string (required)Source file ID, from an Agent API upload in the current workspacepath string (required)Normalized absolute path under /workspace/; directory traversal is not allowedThe request body does not accept extra fields. The source file must come from an Agent API upload in the current workspace.

Request example

curl -sS -X POST "$BASE_URL/agents/environments/ccarenv_xxx/files" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file_id",
    "file_id": "file_xxx",
    "path": "/workspace/input/input.txt"
  }'

Response fields

environment_id stringEnvironment IDobject stringEnvironment file object type, fixed as agent.environment.filepath stringFile path in the environmentsize_bytes integerNumber of bytes writtenThe response does not contain a new source file ID and is not an artifact publication receipt.

Response example

{
  "environment_id": "ccarenv_xxx",
  "object": "agent.environment.file",
  "path": "/workspace/input/input.txt",
  "size_bytes": 18
}

Error codes

HTTP statusError type / codeSolution
400invalid_request_error / invalid_request_errorAdd required fields and fix type and path as described for each field
404not_found_error / not_found_errorUse a source file ID that exists and is visible in the current workspace
400invalid_request_error / invalid_request_error, param=file_idUse a source file uploaded through POST /agents/file
409invalid_request_error / file_not_available, param=file_idUse a source file that passed review and is available
504server_error / environment_file_timeoutRetry later. If it keeps failing, submit a ticket with x-request-id
The error body has the shape {"error":{"type","code","message","param"}}. Gateway errors can use a different structure.