Files API
Manage
List files
/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
limitintegerThe maximum number of objects to be returned in a single response.
orderstringThe ordering to sort the returned files. Use `asc` for ascending and `desc` for descending order.
sort_bystringThe field to sort by. Valid options: `created_at`, `filename`, `size`. Defaults to `created_at`.
pagination_tokenstringThe pagination token returned by the previous list files request.
afterstringOnly included for compatibility. Use `pagination_token` instead.
filterstringAIP-160 filter expression to narrow down results.
Response Body
dataarray<object>List of files.
No parameters.{
"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 file metadata
/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_idstringThe file's `id` returned by upload or list.
Response Body
bytesintegerThe size of the file, in bytes.
created_atintegerThe Unix timestamp (in seconds) for file creation time.
filenamestringThe name of the file.
idstringThe file identifier, which can be used in other API requests.
objectstringThe object type, which is always `file`. Only included for compatability.
purposestringThe intended purpose of the uploaded file. Only included for OAI compatability.
No parameters.{}Update a file's metadata or content
/v1/files/{file_id}
API endpoint for PUT requests to /v1/files/{file_id}.
No parameters.No response.Delete a file
/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_idstringThe file's `id` to delete.
Response Body
deletedbooleanWhether the file was deleted.
idstringThe ID of the file.
objectstringThe object type, which is always "file". Only included for compatibility.
No parameters.{
"id": "file_a128090d-f0c9-4873-bd84-e499777e7417",
"deleted": true
}Last updated:April 28, 2026