Files

files

Files resource group (user-uploaded files).

Wraps the /v1/compliance/apps/chats/files/{claude_file_id} endpoints for metadata, download, and deletion of files a user attached to a chat.

User-uploaded files, generated files, and artifacts share the same download trio (download / download_to_file / download_stream), backed by helpers in downloads. Of the three, only user-uploaded files are deletable — generated files and artifacts have no DELETE endpoint.

File dataclass

Metadata for one user-uploaded chat file.

Attributes:

Name	Type	Description
id	str	Tagged file identifier (claude_file_...).
created_at	str	RFC 3339 creation timestamp.
filename	str | None	Display name, or None when the upload had no filename set.
mime_type	str | None	MIME type of the downloadable variant, or None for files with no downloadable content (e.g. code-interpreter outputs).
size_bytes	int | None	Size of the downloadable variant in bytes, when known.
message_ids	list[str]	Chat message IDs that reference this file. One file can be attached to multiple messages.
extra	dict[str, Any]	Any additional fields the API adds in a later revision.

from_dict classmethod

from_dict(body: Mapping[str, Any]) -> 'File'

Build a File from one decoded record.

Files

Synchronous client for user-uploaded compliance files.

get

get(claude_file_id: str) -> File

Fetch file metadata without downloading the bytes.

download

download(claude_file_id: str) -> bytes

Download the file's bytes in one shot.

Bounded by the client's max_download_bytes cap; raises FileTooLargeError for anything larger. Use download_to_file or download_stream for unbounded reads.

download_to_file

download_to_file(
    claude_file_id: str, dest: PathLike
) -> None

Stream the file's bytes to dest (a path or os.PathLike).

Unbounded — the eager cap exists to protect memory, not disk.

download_stream

download_stream(claude_file_id: str) -> Iterator[bytes]

Yield response chunks to the caller, connection auto-closes.

delete

delete(claude_file_id: str) -> None

Permanently delete the file.

Returns None on success; the server's confirmation payload is discarded.

Raises:

Type	Description
NotFoundError	When claude_file_id does not exist or has already been deleted.
APIError	For any other non-2xx response.

AsyncFiles

Asynchronous client for user-uploaded compliance files.

get async

get(claude_file_id: str) -> File

Async analogue of get.

download async

download(claude_file_id: str) -> bytes

Async analogue of download.

download_to_file async

download_to_file(
    claude_file_id: str, dest: PathLike
) -> None

Async analogue of download_to_file.

download_stream

download_stream(
    claude_file_id: str,
) -> AsyncIterator[bytes]

Async analogue of download_stream.

delete async

delete(claude_file_id: str) -> None

Async analogue of delete.