Documentation

FilesResource

Access via client.files

list()

List files with optional filtering and pagination

async def list(
    *,
    search: Optional[str] = None,
    search_mode: str = "all",  # "all" | "metadata" | "visible_text"
    tags: Optional[list[str]] = None,
    date_from: Optional[datetime] = None,
    date_to: Optional[datetime] = None,
    has_description: Optional[bool] = None,
    ids: Optional[list[str]] = None,  # max 500
    limit: int = 20,  # 1-100
    offset: int = 0,
    sort_by: str = "content_created_at",  # "created_at" | "content_created_at" | "title" | "size_bytes"
    sort_order: str = "desc",  # "asc" | "desc"
) -> FileList

Returns: FileList

list_all()

Auto-paginating async iterator that yields all files matching the criteria

async def list_all(
    *,
    search: Optional[str] = None,
    search_mode: str = "all",
    tags: Optional[list[str]] = None,
    date_from: Optional[datetime] = None,
    date_to: Optional[datetime] = None,
    has_description: Optional[bool] = None,
    sort_by: str = "content_created_at",
    sort_order: str = "desc",
    page_size: int = 50,
) -> AsyncIterator[UserFile]

Yields: UserFile objects one at a time, automatically paginating through all results

get()

Get detailed information about a file

async def get(file_id: str) -> UserFileDetails

Returns: UserFileDetails - Full file details with descriptions, visible text, tags, and processing history

update()

Update file metadata (title and/or tags)

async def update(
    file_id: str,
    *,
    title: Optional[str] = None,  # max 255 chars
    tags: Optional[list[str]] = None,  # max 40 tags, each max 50 chars
) -> UpdateFileResult

delete()

Soft-delete a file (recoverable within 30 days)

async def delete(file_id: str) -> DeleteFileResult

batch_delete()

Delete multiple files in one operation (max 100)

async def batch_delete(file_ids: list[str]) -> BatchDeleteFilesResponse

get_variant()

Get redirect URL for an image variant

async def get_variant(
    file_id: str,
    variant_type: str = "medium_750",  # "original" | "tiny_64" | "small_256" | "medium_750" | "large_1024"
) -> str

download()

Download the original file content

async def download(file_id: str) -> bytes

trigger_variant_generation()

Manually trigger image variant generation (retry failed or generate missing variants)

async def trigger_variant_generation(file_id: str) -> dict[str, Any]

Managing Files Guide

How to list and manage files

File Types

UserFile, UserFileDetails, FileList