Manage

GET /v1/files

List files owned by the authenticated team, paginated. The response always returns a `pagination_token`; pass it back as a query parameter to fetch the next page. The end of the list is reached when the returned `data` array is shorter than `limit`.

Query Parameters

• limit (integer) — The maximum number of objects to be returned in a single response.

• order (string) — The ordering to sort the returned files. Use `asc` for ascending and `desc` for descending order.

• sort_by (string) — The field to sort by. Valid options: `created_at`, `filename`, `size`. Defaults to `created_at`.

• pagination_token (string) — The pagination token returned by the previous list files request.

• after (string) — Only included for compatibility. Use `pagination_token` instead.

• filter (string) — AIP-160 filter expression to narrow down results.

  **Filterable fields:**

  Field	Type	Description
  `name` (or `file_name`)	string	Fuzzy match on filename
  `file_id`	string	Exact match on file ID
  `size_bytes`	integer	File size in bytes
  `content_type`	string	Partial match on MIME type (e.g. `"pdf"` matches `"application/pdf"`)
  `created_at`	timestamp	RFC 3339 timestamp (e.g. `"2024-01-01T00:00:00Z"`)
  `expires_at`	timestamp	RFC 3339 timestamp
  `upload_status`	string	Upload status (`"Complete"`)
  `user_defined_id`	string	Exact match on user-defined ID

  **Operators:** `=`, `!=`, `>`, `>=`, `<`, `<=`

  **Logical:** `AND`, `OR`, `NOT`

  **Examples:** - `name:"quarterly report"` — fuzzy match on filename - `content_type = "pdf"` — files with PDF content type - `size_bytes > 1000000 AND created_at > "2024-01-01T00:00:00Z"` — files larger than 1 MB created after Jan 1, 2024 - `file_id = "file_abc123"` — exact file ID match

Response Body

• data (array<object>, required) — List of files.

  • bytes (integer, required) — The size of the file, in bytes.

  • created_at (integer, required) — The Unix timestamp (in seconds) for file creation time.

  • expires_at (integer | null) — The Unix timestamp (in seconds) for file expiry time. null if file does not expire.

  • filename (string, required) — The name of the file.

  • id (string, required) — The file identifier, which can be used in other API requests.

  • object (string, required) — The object type, which is always `file`. Only included for compatability.

  • public_url (string | null) — Public URL for the file. Only present when the file has an active public URL.

  • public_url_expires_at (integer | null) — Unix timestamp (seconds) when the public URL expires. Only present when the public URL has an independent expiry.

  • purpose (string) — The intended purpose of the uploaded file. Only included for OAI compatability.

• pagination_token (string | null) — Pagination token to use with next request.

**Response example:**

{
  "data": [
    {
      "id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
      "object": "file",
      "bytes": 12345,
      "created_at": 1762345678,
      "expires_at": null,
      "filename": "document.pdf",
      "purpose": ""
    }
  ],
  "pagination_token": "file_a128090d-f0c9-4873-bd84-e499777e7417"
}

GET /v1/files/{file_id}

Retrieve metadata for a single file by ID. Errors with 404 if the file doesn't exist, has been deleted, or has passed its `expires_at`.

Path Parameters

• file_id (string, required) — The file's `id` returned by upload or list.

Response Body

• bytes (integer, required) — The size of the file, in bytes.

• created_at (integer, required) — The Unix timestamp (in seconds) for file creation time.

• expires_at (integer | null) — The Unix timestamp (in seconds) for file expiry time. null if file does not expire.

• filename (string, required) — The name of the file.

• id (string, required) — The file identifier, which can be used in other API requests.

• object (string, required) — The object type, which is always `file`. Only included for compatability.

• public_url (string | null) — Public URL for the file. Only present when the file has an active public URL.

• public_url_expires_at (integer | null) — Unix timestamp (seconds) when the public URL expires. Only present when the public URL has an independent expiry.

• purpose (string) — The intended purpose of the uploaded file. Only included for OAI compatability.

**Response example:**

{}

PUT /v1/files/{file_id}

API endpoint for PUT requests to /v1/files/{file_id}.

Method: PUT
Path: /v1/files/{file_id}

DELETE /v1/files/{file_id}

Delete a file by ID. After this returns, the file no longer appears in `GET /v1/files`, content download returns 404, and the ID can no longer be referenced in chat attachments.

Path Parameters

• file_id (string, required) — The file's `id` to delete.

Response Body

• deleted (boolean, required) — Whether the file was deleted.

• id (string, required) — The ID of the file.

• object (string, required) — The object type, which is always "file". Only included for compatibility.

**Response example:**

{
  "id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
  "deleted": true
}