Files - Python SDK

Files method reference

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*/*