---
title: "Promote a container file into workspace documents"
method: POST
path: "/containers/{container_id}/files/{file_id}/promote"
tags: ["Containers"]
---

# Promote a container file into workspace documents

`POST /containers/{container_id}/files/{file_id}/promote`

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.

## Path parameters

- `container_id` string, 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.
- `file_id` string, required — Container file id (`cfile_` + base64url of the file path).

## Response `200`

The promoted file, as a workspace document.

- union — A stored file. The shape is negotiated per request — see the endpoint description.
  - OpenRouterFile — A stored file in the OpenRouter superset shape: Anthropic-shaped, plus OpenRouter-only fields.
    - `_shape` 'openrouter', required
    - `created_at` string, required
    - `downloadable` boolean, required
    - `filename` string, required
    - `id` string, required
    - `mime_type` string, required
    - `size_bytes` integer, required
    - `type` 'file', required
  - OpenAIFile — A stored file in OpenAI's Files API shape.
    - `_shape` 'openai', required
    - `bytes` integer, required
    - `created_at` integer, required
    - `filename` string, required
    - `id` string, required
    - `object` 'file', required
    - `purpose` 'assistants' | 'batch' | 'fine-tune' | 'vision' | 'user_data' | 'evals' | 'assistants_output' | 'batch_output' | 'fine-tune-results', required
    - `status` 'processed', required
  - AnthropicFile — A stored file in Anthropic's Files API shape.
    - `_shape` 'anthropic', required
    - `created_at` string, required
    - `downloadable` boolean, required
    - `filename` string, required
    - `id` string, required
    - `mime_type` string, required
    - `size_bytes` integer, required
    - `type` 'file', required

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `403` — Forbidden - Authentication successful but insufficient permissions
- `404` — Not Found - Resource does not exist
- `413` — Payload Too Large - Request payload exceeds size limits
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - Unexpected server error
- `503` — Service Unavailable - Service temporarily unavailable

## Changes

- **2026-08-25** `95cc7c8ba0e0` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/containers/:container_id/files/:file_id/promote/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/dc4ac69fb923?raw)