API Reference

Files

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List Files

FileListPageResponse Files.List(FileListParams?parameters, CancellationTokencancellationToken = default)

GET/api/v1/beta/files

List files with optional filtering and pagination.

Filter by file_name, file_ids, or external_file_id. Supports cursor-based pagination and custom ordering.

ParametersExpand Collapse

FileListParams parameters

IReadOnlyList<string>? expand

Fields to expand on each file.

string? externalFileID

Filter by external file ID.

IReadOnlyList<string>? fileIds

Filter by specific file IDs.

string? fileName

Filter by file name (exact match).

string? orderBy

A comma-separated list of fields to order by, sorted in ascending order. Use ‘field_name desc’ to specify descending order.

string? organizationID

Long? pageSize

The maximum number of items to return. Defaults to 50, maximum is 1000.

maximum1000

minimum1

string? pageToken

A page token received from a previous list call. Provide this to retrieve the subsequent page.

string? projectID

ReturnsExpand Collapse

class FileListPageResponse:

Paginated list of files.

required IReadOnlyList<FileListResponse> Items

The list of items.

required string ID

Unique file identifier

required string Name

File name including extension

maxLength3000

minLength1

required string ProjectID

Project this file belongs to

formatuuid

PresignedUrl? DownloadUrl

Schema for a presigned URL.

required DateTimeOffset ExpiresAt

The time at which the presigned URL expires

formatdate-time

required string Url

A presigned URL for IO operations against a private file

formaturi

minLength1

IReadOnlyDictionary<string, string>? FormFields

Form fields for a presigned POST request

DateTimeOffset? ExpiresAt

When the file expires and may be automatically removed. Null means no expiration.

formatdate-time

string? ExternalFileID

Optional ID for correlating with an external system

string? FileType

File extension (pdf, docx, png, etc.)

maxLength3000

minLength1

DateTimeOffset? LastModifiedAt

When the file was last modified (ISO 8601)

formatdate-time

string? Purpose

How the file will be used: user_data, parse, extract, classify, split, sheet, or agent_app

string? NextPageToken

A token, which can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

Long? TotalSize

The total number of items available. This is only populated when specifically requested. The value may be an estimate and can be used for display purposes only.

List Files

C#

HTTP

TypeScript

Python

Go

Java

C#

CLI Tool

FileListParams parameters = new();

var page = await client.Files.List(parameters);
await foreach (var item in page.Paginate())
{
    Console.WriteLine(item);
}

200 example

{
  "items": [
    {
      "id": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "name": "invoice.pdf",
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "download_url": {
        "expires_at": "2019-12-27T18:11:19.117Z",
        "url": "https://example.com",
        "form_fields": {
          "foo": "string"
        }
      },
      "expires_at": "2019-12-27T18:11:19.117Z",
      "external_file_id": "ext-12345",
      "file_type": "pdf",
      "last_modified_at": "2019-12-27T18:11:19.117Z",
      "purpose": "parse"
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}

Returns Examples

200 example

{
  "items": [
    {
      "id": "dfl-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "name": "invoice.pdf",
      "project_id": "123e4567-e89b-12d3-a456-426614174000",
      "download_url": {
        "expires_at": "2019-12-27T18:11:19.117Z",
        "url": "https://example.com",
        "form_fields": {
          "foo": "string"
        }
      },
      "expires_at": "2019-12-27T18:11:19.117Z",
      "external_file_id": "ext-12345",
      "file_type": "pdf",
      "last_modified_at": "2019-12-27T18:11:19.117Z",
      "purpose": "parse"
    }
  ],
  "next_page_token": "next_page_token",
  "total_size": 0
}