Overview
Containers endpointsAvailable Operations
- list_container_files - List container files
- get_container_file - Retrieve a container file
- download_container_file_content - Download container file content
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 withlimit and after (pass the previous page’s last_id); has_more: true always means the next page is fetchable that way.
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: a container file id from a previous page (typically last_id); listing resumes strictly after that file. | cfile_b3V0L3JlcG9ydC5jc3Y |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.ContainerFileListResponseErrors
| 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.ContainerFileErrors
| 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.ResponseErrors
| 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 | */* |