Files API
Manage
List files
/v1/files
List files.
Query parameters
team_id
string
team_id of the team that owns the files. If `None`, the team ID will be derived from your request credentials.
prefix
string
Optional prefix to filter files by name. DEPRECATED: Use filter field instead with "name:prefix*"
limit
integer
A limit on the number of objects to be returned. Max 100 items per request. If `None`, set the default to 100 items.
next_token
string
A token for use in pagination.
order
string
The ordering to sort the returned files (ASCENDING or DESCENDING). Defined in shared.proto. Default is DESCENDING if omitted.
sort_by
string
The parameter that the files will be sorted by. If not provided, the default is to sort by `created_at` (age).
filter
string
Filter expression to narrow down results. Supports filtering on: file_id, file_name (or name), size_bytes, content_type, created_at, upload_status, user_defined_id Examples: - 'name:"report"' - 'file_id = "file_123"' - 'size_bytes > 1000 AND upload_status = "Complete"' - 'content_type = "application/pdf"' - 'created_at > "2024-01-01T00:00:00Z"'
Response Body
files
array
List of files.
next_token
string
Token to be sent in the next request for correct pagination.
Get file metadata
/v1/files/{file_id}
Get file metadata.
Path parameters
file_id
string
required
file_id of the file to request.
Query parameters
team_id
string
team_id of the team that owns the file. If `None`, the team ID will be derived from your request credentials.
Response Body
file_id
string
The document ID.
name
string
The name of the document.
size_bytes
string
The size of the document, in bytes.
content_type
string
MIME type.
created_at
string
The Unix timestamp for when the document was created.
expires_at
string
The Unix timestamp for when the document will expire.
Blake 3 hash of the document,
string
Expected values: "Initializing", "Uploading", "Complete", "Failed"
string
upload_error_message
string
Error message if upload failed.
processing_status
string
Processing status of the file (pending, processing, complete, failed, skipped).
file_path
string
Optional: hierarchical path for the file (e.g., "folder1/subfolder"). This is relative to the team root and does not include the filename.
Update a file's metadata or content
/v1/files/{file_id}
Update a file's metadata or content.
Path parameters
file_id
string
required
file_id of the file to update.
Request Body
Response Body
file_id
string
The document ID.
name
string
The name of the document.
size_bytes
string
The size of the document, in bytes.
content_type
string
MIME type.
created_at
string
The Unix timestamp for when the document was created.
expires_at
string
The Unix timestamp for when the document will expire.
Blake 3 hash of the document,
string
Expected values: "Initializing", "Uploading", "Complete", "Failed"
string
upload_error_message
string
Error message if upload failed.
processing_status
string
Processing status of the file (pending, processing, complete, failed, skipped).
file_path
string
Optional: hierarchical path for the file (e.g., "folder1/subfolder"). This is relative to the team root and does not include the filename.
Delete a file
/v1/files/{file_id}
Delete a file.
Path parameters
file_id
string
required
file_id of the file to delete.
Query parameters
team_id
string
team_id of the team that owns the file. If `None`, the team ID will be derived from your request credentials.
Did you find this page helpful?