Sign in
Containers

Promote a container file into workspace documents

Copies a file from the container's sandbox prefix into the workspace's durable document storage, so it outlives the container. Returns the new document in the Files API shape, with a durable file id in the documents namespace. The copy counts against the workspace's storage quota. Unlike a direct upload, promoted files are downloadable.

post/containers/{container_id}/files/{file_id}/promote

Path parameters

container_idstring required

The canonical container id, exactly as returned in a bash/shell tool result — a restarted session has its own -r<nonce>-suffixed id. A session-derived id is always sess_ + the sanitized session key, which is not necessarily the raw session id that was sent.

Example:sess_abc123

The canonical container id, exactly as returned in a bash/shell tool result — a restarted session has its own -r<nonce>-suffixed id. A session-derived id is always sess_ + the sanitized session key, which is not necessarily the raw session id that was sent.

file_idstring required

Container file id (cfile_ + base64url of the file path).

Example:cfile_b3V0L3JlcG9ydC5jc3Y

Container file id (cfile_ + base64url of the file path).

Response

The promoted file, as a workspace document.

OR
OR

Example response

{
  "_shape": "openrouter",
  "created_at": "2025-01-01T00:00:00Z",
  "downloadable": false,
  "filename": "document.pdf",
  "id": "or_file_011CNha8iCJcU1wXNR6q4V8w",
  "mime_type": "application/pdf",
  "size_bytes": 1024000,
  "type": "file"
}

Changes