Files - Python SDK

Files method reference

The Python SDK and docs are currently in beta. Report issues on GitHub.

Overview

Files endpoints

Available Operations

list

Lists files belonging to the workspace of the authenticating API key.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.files.list()
12
13 while res is not None:
14 # Handle items
15
16 res = res.next()

Parameters

ParameterTypeRequiredDescriptionExample
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
limitOptional[int]Maximum number of files to return (1–1000).100
cursorOptional[str]Opaque pagination cursor from a previous response.eyJjdXJzb3IiOiJmaWxlXzAxMUNOaGE4aUNKY1Uxd1hOUjZxNFY4dyJ9
workspace_idOptional[str]Workspace to scope the request to. Defaults to the caller’s default workspace.a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

operations.ListFilesResponse

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

upload

Uploads a file to be referenced in future API calls. The file is stored under the workspace of the authenticating API key. Maximum file size: 100 MB.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.files.upload(file={
12 "file_name": "example.file",
13 "content": open("example.file", "rb"),
14 })
15
16 # Handle response
17 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
fileoperations.File✔️N/A
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
workspace_idOptional[str]Workspace to scope the request to. Defaults to the caller’s default workspace.a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.FileMetadata

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.ForbiddenResponseError403application/json
errors.PayloadTooLargeResponseError413application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

delete

Deletes a file owned by the requesting workspace. Deletion is irreversible.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.files.delete(file_id="file_011CNha8iCJcU1wXNR6q4V8w")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
file_idstr✔️N/Afile_011CNha8iCJcU1wXNR6q4V8w
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
workspace_idOptional[str]Workspace to scope the request to. Defaults to the caller’s default workspace.a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.FileDeleteResponse

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

retrieve

Retrieves metadata for a single file owned by the requesting workspace.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.files.retrieve(file_id="file_011CNha8iCJcU1wXNR6q4V8w")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
file_idstr✔️N/Afile_011CNha8iCJcU1wXNR6q4V8w
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
workspace_idOptional[str]Workspace to scope the request to. Defaults to the caller’s default workspace.a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

components.FileMetadata

Errors

Error TypeStatus CodeContent Type
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*

download

Downloads the raw bytes of a file. Only files created server-side are downloadable; uploaded files return 400.

Example Usage

1from openrouter import OpenRouter
2import os
3
4with OpenRouter(
5 http_referer="<value>",
6 x_open_router_title="<value>",
7 x_open_router_categories="<value>",
8 api_key=os.getenv("OPENROUTER_API_KEY", ""),
9) as open_router:
10
11 res = open_router.files.download(file_id="file_011CNha8iCJcU1wXNR6q4V8w")
12
13 # Handle response
14 print(res)

Parameters

ParameterTypeRequiredDescriptionExample
file_idstr✔️N/Afile_011CNha8iCJcU1wXNR6q4V8w
http_refererOptional[str]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_titleOptional[str]The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
x_open_router_categoriesOptional[str]Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
workspace_idOptional[str]Workspace to scope the request to. Defaults to the caller’s default workspace.a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
retriesOptional[utils.RetryConfig]Configuration to override the default retry behavior of the client.

Response

httpx.Response

Errors

Error TypeStatus CodeContent Type
errors.BadRequestResponseError400application/json
errors.UnauthorizedResponseError401application/json
errors.NotFoundResponseError404application/json
errors.TooManyRequestsResponseError429application/json
errors.InternalServerResponseError500application/json
errors.OpenRouterDefaultError4XX, 5XX*/*