Containers - OpenRouter | Documentation

Overview

Containers endpoints

Available Operations

list_container_files - List container files
get_container_file - Retrieve a container file
download_container_file_content - Download container file content
promote_container_file - Promote a container file into workspace documents

list_container_files

Lists the files in a container, in lexicographic path order. The container id is the canonical id returned in bash/shell tool results; a restarted session is a separate container with its own id. Paginate with limit and after (pass the previous page’s last_id); has_more: true always means the next page is fetchable that way. last_id is the resume cursor: it is the last listed file’s id, except when a page ends at the per-request scan bound on hidden bookkeeping objects, where it names the scan position instead and may not appear in data (which can then be empty).

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.containers.list_container_files(container_id="sess_abc123", limit=100)

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`container_id`	str	:heavy_check_mark:	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.	sess_abc123
`http_referer`	Optional[str]	:heavy_minus_sign:	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`limit`	Optional[int]	:heavy_minus_sign:	Maximum number of files to return (1-1000). Defaults to 100 when absent.	100
`after`	Optional[str]	:heavy_minus_sign:	Forward cursor: the previous page’s `last_id` (or any container file id); listing resumes strictly after that path.	cfile_b3V0L3JlcG9ydC5jc3Y
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.ContainerFileListResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get_container_file

Returns the metadata of a single file in a container.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.containers.get_container_file(container_id="sess_abc123", file_id="cfile_b3V0L3JlcG9ydC5jc3Y")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`container_id`	str	:heavy_check_mark:	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.	sess_abc123
`file_id`	str	:heavy_check_mark:	Container file id (`cfile_` + base64url of the file path).	cfile_b3V0L3JlcG9ydC5jc3Y
`http_referer`	Optional[str]	:heavy_minus_sign:	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.ContainerFile

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

download_container_file_content

Streams the raw bytes of a file in a container.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.containers.download_container_file_content(container_id="sess_abc123", file_id="cfile_b3V0L3JlcG9ydC5jc3Y")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`container_id`	str	:heavy_check_mark:	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.	sess_abc123
`file_id`	str	:heavy_check_mark:	Container file id (`cfile_` + base64url of the file path).	cfile_b3V0L3JlcG9ydC5jc3Y
`http_referer`	Optional[str]	:heavy_minus_sign:	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

httpx.Response

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

promote_container_file

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.

Example Usage

from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.containers.promote_container_file(container_id="sess_abc123", file_id="cfile_b3V0L3JlcG9ydC5jc3Y")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`container_id`	str	:heavy_check_mark:	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.	sess_abc123
`file_id`	str	:heavy_check_mark:	Container file id (`cfile_` + base64url of the file path).	cfile_b3V0L3JlcG9ydC5jc3Y
`http_referer`	Optional[str]	:heavy_minus_sign:	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.FileResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.ForbiddenResponseError	403	application/json
errors.NotFoundResponseError	404	application/json
errors.PayloadTooLargeResponseError	413	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

​Overview

​Available Operations

​list_container_files

​Example Usage

​Parameters

​Response

​Errors

​get_container_file

​Example Usage

​Parameters

​Response

​Errors

​download_container_file_content

​Example Usage

​Parameters

​Response

​Errors

​promote_container_file

​Example Usage

​Parameters

​Response

​Errors

Overview

Available Operations

list_container_files

Example Usage

Parameters

Response

Errors

get_container_file

Example Usage

Parameters

Response

Errors

download_container_file_content

Example Usage

Parameters

Response

Errors

promote_container_file

Example Usage

Parameters

Response

Errors