Files

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

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.files.list();

  for await (const page of result) {
    console.log(page);
  }
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { filesList } from "@openrouter/sdk/funcs/filesList.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await filesList(openRouter);
  if (res.ok) {
    const { value: result } = res;
    for await (const page of result) {
    console.log(page);
  }
  } else {
    console.log("filesList failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.ListFilesRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<operations.ListFilesResponse>

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.BadGatewayResponseError	502	application/json
errors.ServiceUnavailableResponseError	503	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; empty files are rejected. The file type is determined from the file contents — not the filename or the declared content type — and must be a PDF, a PNG/JPEG/GIF/WebP image, a DOCX/XLSX/PPTX document, an MP3/WAV/FLAC/OGG audio file, or UTF-8 text. Text is reported by its structure as application/json, application/x-ndjson, text/csv, text/markdown, or text/plain.

Example Usage

import { OpenRouter } from "@openrouter/sdk";
import { openAsBlob } from "node:fs";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.files.upload({
    provider: "openai",
    requestBody: {
      file: await openAsBlob("example.file"),
    },
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { filesUpload } from "@openrouter/sdk/funcs/filesUpload.js";
import { openAsBlob } from "node:fs";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await filesUpload(openRouter, {
    provider: "openai",
    requestBody: {
      file: await openAsBlob("example.file"),
    },
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("filesUpload failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.UploadFileRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.FileResponse>

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.BadGatewayResponseError	502	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

delete

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

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.files.delete({
    fileId: "file_011CNha8iCJcU1wXNR6q4V8w",
    provider: "openai",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { filesDelete } from "@openrouter/sdk/funcs/filesDelete.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await filesDelete(openRouter, {
    fileId: "file_011CNha8iCJcU1wXNR6q4V8w",
    provider: "openai",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("filesDelete failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.DeleteFileRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.FileDeleteResponse>

Errors

Error Type	Status Code	Content Type
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.BadGatewayResponseError	502	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

retrieve

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

Example Usage

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.files.retrieve({
    fileId: "file_011CNha8iCJcU1wXNR6q4V8w",
    provider: "openai",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { filesRetrieve } from "@openrouter/sdk/funcs/filesRetrieve.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await filesRetrieve(openRouter, {
    fileId: "file_011CNha8iCJcU1wXNR6q4V8w",
    provider: "openai",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("filesRetrieve failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.GetFileMetadataRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<models.FileResponse>

Errors

Error Type	Status Code	Content Type
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.BadGatewayResponseError	502	application/json
errors.ServiceUnavailableResponseError	503	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

import { OpenRouter } from "@openrouter/sdk";

const openRouter = new OpenRouter({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const result = await openRouter.files.download({
    fileId: "file_011CNha8iCJcU1wXNR6q4V8w",
    provider: "openai",
  });

  console.log(result);
}

run();

Standalone function

The standalone function version of this method:

import { OpenRouterCore } from "@openrouter/sdk/core.js";
import { filesDownload } from "@openrouter/sdk/funcs/filesDownload.js";

// Use `OpenRouterCore` for best tree-shaking performance.
// You can create one instance of it to use across an application.
const openRouter = new OpenRouterCore({
  httpReferer: "<value>",
  appTitle: "<value>",
  appCategories: "<value>",
  apiKey: process.env["OPENROUTER_API_KEY"] ?? "",
});

async function run() {
  const res = await filesDownload(openRouter, {
    fileId: "file_011CNha8iCJcU1wXNR6q4V8w",
    provider: "openai",
  });
  if (res.ok) {
    const { value: result } = res;
    console.log(result);
  } else {
    console.log("filesDownload failed:", res.error);
  }
}

run();

Parameters

Parameter	Type	Required	Description
`request`	operations.DownloadFileContentRequest	:heavy_check_mark:	The request object to use for the request.
`options`	RequestOptions	:heavy_minus_sign:	Used to set various options for making HTTP requests.
`options.fetchOptions`	RequestInit	:heavy_minus_sign:	Options that are passed to the underlying HTTP request. This can be used to inject extra headers for examples. All `Request` options, except `method` and `body`, are allowed.
`options.retries`	RetryConfig	:heavy_minus_sign:	Enables retrying HTTP requests under certain failure conditions.

Response

Promise<ReadableStream<Uint8Array>>

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.BadGatewayResponseError	502	application/json
errors.ServiceUnavailableResponseError	503	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

TypeScript SDK

Python SDK

Go SDK

DevTools

Overview

Available Operations

list

Example Usage

Standalone function

Parameters

Response

Errors

upload

Example Usage

Standalone function

Parameters

Response

Errors

delete

Example Usage

Standalone function

Parameters

Response

Errors

retrieve

Example Usage

Standalone function

Parameters

Response

Errors

download

Example Usage

Standalone function

Parameters

Response

Errors

​Overview

​Available Operations

​list

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​upload

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​delete

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​retrieve

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

​download

​Example Usage

​Standalone function

​Parameters

​Response

​Errors

Overview

Available Operations

list

Example Usage

Standalone function

Parameters

Response

Errors

upload

Example Usage

Standalone function

Parameters

Response

Errors

delete

Example Usage

Standalone function

Parameters

Response

Errors

retrieve

Example Usage

Standalone function

Parameters

Response

Errors

download

Example Usage

Standalone function

Parameters

Response

Errors