Files - OpenRouter | Documentation

Overview

Files endpoints

Available Operations

list - List files
upload - Upload a file
delete - Delete a file
retrieve - Get file metadata
download - Download file content

list

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

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.files.list()

    while res is not None:
        # Handle items

        res = res.next()

Parameters

Parameter	Type	Required	Description	Example
`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).	100
`cursor`	Optional[str]	:heavy_minus_sign:	Opaque pagination cursor from a previous response.	eyJjdXJzb3IiOiJmaWxlXzAxMUNOaGE4aUNKY1Uxd1hOUjZxNFY4dyJ9
`workspace_id`	Optional[str]	:heavy_minus_sign:	Workspace to scope the request to. Defaults to the caller’s default workspace.	a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

operations.ListFilesResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 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

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.files.upload(file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`file`	operations.UploadFileFile	:heavy_check_mark:	N/A
`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.
`workspace_id`	Optional[str]	:heavy_minus_sign:	Workspace to scope the request to. Defaults to the caller’s default workspace.	a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.FileMetadata

Errors

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

delete

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

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.files.delete(file_id="file_011CNha8iCJcU1wXNR6q4V8w")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`file_id`	str	:heavy_check_mark:	N/A	file_011CNha8iCJcU1wXNR6q4V8w
`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.
`workspace_id`	Optional[str]	:heavy_minus_sign:	Workspace to scope the request to. Defaults to the caller’s default workspace.	a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.FileDeleteResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

retrieve

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

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.files.retrieve(file_id="file_011CNha8iCJcU1wXNR6q4V8w")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`file_id`	str	:heavy_check_mark:	N/A	file_011CNha8iCJcU1wXNR6q4V8w
`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.
`workspace_id`	Optional[str]	:heavy_minus_sign:	Workspace to scope the request to. Defaults to the caller’s default workspace.	a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.FileMetadata

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

download

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

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.files.download(file_id="file_011CNha8iCJcU1wXNR6q4V8w")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`file_id`	str	:heavy_check_mark:	N/A	file_011CNha8iCJcU1wXNR6q4V8w
`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.
`workspace_id`	Optional[str]	:heavy_minus_sign:	Workspace to scope the request to. Defaults to the caller’s default workspace.	a103d8b6-42f0-4e50-9a3c-bf41e2c3c1a7
`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.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

​Overview

​Available Operations

​list

​Example Usage

​Parameters

​Response

​Errors

​upload

​Example Usage

​Parameters

​Response

​Errors

​delete

​Example Usage

​Parameters

​Response

​Errors

​retrieve

​Example Usage

​Parameters

​Response

​Errors

​download

​Example Usage

​Parameters

​Response

​Errors

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

upload

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

retrieve

Example Usage

Parameters

Response

Errors

download

Example Usage

Parameters

Response

Errors