Chats¶

chats ¶

Chats resource group.

Wraps three Compliance API endpoints:

GET /v1/compliance/apps/chats — cursor-paginated chat metadata list. user_ids[] is required and must carry 1–10 IDs; the SDK validates the length client-side (a cheap input-shape check) and raises ValueError outside that range without touching the network.
GET /v1/compliance/apps/chats/{claude_chat_id}/messages — the only way to fetch a single chat. Returns the chat metadata alongside one cursor-paginated page of messages. Exposed via two methods:
get returns a ChatMessagesPage carrying both the chat and the message page so callers can read either.
iter_messages drives the same endpoint with a custom cursor loop and yields Message objects one at a time.
DELETE /v1/compliance/apps/chats/{claude_chat_id} — destructive delete. The chat record persists with deleted_at populated (soft-delete data model) but cannot be undone. Returns None.

Note that the API does not expose a separate GET /v1/compliance/apps/chats/{id} single-fetch endpoint, so get uses the messages endpoint and reads the chat fields from its response.

Chat `dataclass` ¶

A single chat's metadata (list shape).

Attributes:

Name	Type	Description
`id`	`str`	Tagged chat identifier (`claude_chat_...`).
`name`	`str`	Display name.
`created_at`	`str`	RFC 3339 creation timestamp.
`updated_at`	`str`	RFC 3339 last-update timestamp.
`href`	`str`	Direct claude.ai URL for the chat.
`model`	`str \| None`	Model the chat ran against (e.g. `claude-opus-5`), or `None` for legacy chats that never had a model recorded.
`organization_id`	`str \| None`	Owning organisation's tagged ID. Deprecated by the API in favour of `organization_uuid`.
`organization_uuid`	`str \| None`	Owning organisation's UUID. Prefer this over `organization_id`. `None` only if the API omits it.
`deleted_at`	`str \| None`	RFC 3339 deletion timestamp, or `None` while the chat is still active. A chat deleted in claude.ai stays listed with this field set and an empty `name`, but its message content is gone.
`project_id`	`str \| None`	Owning project's tagged ID, or `None` for standalone chats.
`user`	`dict[str, Any] \| None`	Creator info (`id`, `email_address`) or `None` when the creator's account has been deleted or they are no longer in an organisation the key can read. Kept as a raw dict.
`extra`	`dict[str, Any]`	Any additional fields the API adds in a later revision.

from_dict `classmethod` ¶

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

Build a Chat from one decoded record.

Strips the message-page wrapper keys before delegating to parse_with_extra so the chat's extra does not carry pagination cruft when the body comes from the /messages endpoint.

Message `dataclass` ¶

A single message within a chat.

Content blocks, file attachments, and artifact references are stored as raw dicts — typed unions for those nested shapes can land later if they earn their keep.

Attributes:

Name	Type	Description
`id`	`str`	Tagged message identifier (`claude_chat_msg_...`).
`role`	`str`	`"user"` or `"assistant"`.
`created_at`	`str`	RFC 3339 creation timestamp.
`content`	`list[dict[str, Any]]`	List of content blocks. Each block has at least a `type` discriminator (e.g. `"text"`).
`files`	`list[dict[str, Any]] \| None`	User-uploaded file references attached to the message, or `None` when the message has no files.
`generated_files`	`list[dict[str, Any]] \| None`	References to files the assistant produced via tool use (PDFs, spreadsheets, etc.), or `None` when there are none.
`artifacts`	`list[dict[str, Any]] \| None`	Artifact references generated alongside an assistant message, or `None` when there are none.
`extra`	`dict[str, Any]`	Any additional fields the API adds in a later revision.

from_dict `classmethod` ¶

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

Build a Message from one decoded record.

ChatMessagesPage `dataclass` ¶

Result of get — chat metadata plus one page of messages.

The Compliance API returns these together from a single endpoint, so this wrapper makes the join explicit on the SDK side rather than scattering pagination fields across Chat.

Attributes:

Name	Type	Description
`chat`	`Chat`	The chat's metadata.
`messages`	`CursorPage[Message]`	One `CursorPage` of `Message` for the chat. Drive further pages by passing `messages.last_id` as `after_id` to the next `get` call.

from_dict `classmethod` ¶

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

Build a ChatMessagesPage from the /messages response.

Chats ¶

Synchronous client for the Chats endpoints.

list ¶

list(
    *,
    user_ids: StrList | None = None,
    organization_ids: StrList | None = None,
    project_ids: StrList | None = None,
    order_by: str | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    updated_at_gte: str | None = None,
    updated_at_gt: str | None = None,
    updated_at_lte: str | None = None,
    updated_at_lt: str | None = None,
    after_id: str | None = None,
    before_id: str | None = None,
    limit: int | None = None
) -> CursorPage[Chat]

Fetch one cursor-paginated page of chats.

Omit user_ids for an organisation-wide query. Combined with order_by="updated_at", that is the recommended way to keep an export current: one paginated walk picks up new, modified, and claude.ai-deleted chats for every user without enumerating users first.

Several combinations are rejected by the server rather than checked here:

project_ids requires user_ids; it is not supported on organisation-wide queries.
order_by="updated_at" is rejected when user_ids is set.
before_id (backward paging) works only with user_ids.
Time bounds must match the sort key — created_at.* with order_by="created_at", updated_at.* with order_by="updated_at".
Cursors are bound to the sort key, so an after_id issued under one order_by is rejected under the other.

Parameters:

Name	Type	Description	Default
`user_ids`	`StrList \| None`	1–10 user IDs to filter on, or `None` (the default) for an organisation-wide query. A supplied list outside 1–10 raises `ValueError` locally before sending.	`None`
`organization_ids`	`StrList \| None`	Optional org filter.	`None`
`project_ids`	`StrList \| None`	Optional project filter. Requires `user_ids`.	`None`
`order_by`	`str \| None`	Sort key, `"created_at"` (server default) or `"updated_at"`.	`None`
`created_at_gte`	`str \| None`	`created_at >= value` (RFC 3339).	`None`
`created_at_gt`	`str \| None`	`created_at > value` (RFC 3339).	`None`
`created_at_lte`	`str \| None`	`created_at <= value` (RFC 3339).	`None`
`created_at_lt`	`str \| None`	`created_at < value` (RFC 3339).	`None`
`updated_at_gte`	`str \| None`	`updated_at >= value` (RFC 3339).	`None`
`updated_at_gt`	`str \| None`	`updated_at > value` (RFC 3339).	`None`
`updated_at_lte`	`str \| None`	`updated_at <= value` (RFC 3339).	`None`
`updated_at_lt`	`str \| None`	`updated_at < value` (RFC 3339).	`None`
`after_id`	`str \| None`	Cursor for forward pagination.	`None`
`before_id`	`str \| None`	Cursor for backward pagination. Mutually exclusive with `after_id`.	`None`
`limit`	`int \| None`	Maximum results, default 100, max 1000.	`None`

Raises:

Type	Description
`ValueError`	When `user_ids` is supplied but empty or longer than 10.

Warns:

Type	Description
`DeprecationWarning`	When `user_ids` is combined with any `updated_at` bound. The API rejects that combination after 2026-09-22.

iter ¶

iter(
    *,
    user_ids: StrList | None = None,
    organization_ids: StrList | None = None,
    project_ids: StrList | None = None,
    order_by: str | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    updated_at_gte: str | None = None,
    updated_at_gt: str | None = None,
    updated_at_lte: str | None = None,
    updated_at_lt: str | None = None,
    limit: int | None = None
) -> Iterator[Chat]

Iterate every matching chat, auto-paginating.

Same filters as list except that after_id / before_id are managed by the iterator.

Raises:

Type	Description
`ValueError`	When `user_ids` is empty or longer than 10.

get ¶

get(
    chat_id: str,
    *,
    after_id: str | None = None,
    before_id: str | None = None,
    limit: int | None = None
) -> ChatMessagesPage

Fetch one chat's metadata + a page of its messages.

The Compliance API returns chat metadata and a message page from a single endpoint; the SDK exposes them together via ChatMessagesPage.

Parameters:

Name	Type	Description	Default
`chat_id`	`str`	Tagged chat identifier (`claude_chat_...`).	required
`after_id`	`str \| None`	Cursor for forward pagination of messages.	`None`
`before_id`	`str \| None`	Cursor for backward pagination of messages.	`None`
`limit`	`int \| None`	Maximum messages on the returned page. When omitted, the server returns the full message set in one response.	`None`

iter_messages ¶

iter_messages(
    chat_id: str, *, limit: int | None = None
) -> Iterator[Message]

Iterate every message in a chat, auto-paginating.

Parameters:

Name	Type	Description	Default
`chat_id`	`str`	Tagged chat identifier.	required
`limit`	`int \| None`	Per-page maximum (max 1000). Omit to let the server return the full set in one response.	`None`

delete ¶

delete(chat_id: str) -> None

Delete a chat (marks deleted_at; irreversible).

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

AsyncChats ¶

Asynchronous client for the Chats endpoints.

list `async` ¶

list(
    *,
    user_ids: StrList | None = None,
    organization_ids: StrList | None = None,
    project_ids: StrList | None = None,
    order_by: str | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    updated_at_gte: str | None = None,
    updated_at_gt: str | None = None,
    updated_at_lte: str | None = None,
    updated_at_lt: str | None = None,
    after_id: str | None = None,
    before_id: str | None = None,
    limit: int | None = None
) -> CursorPage[Chat]

Async analogue of list.

iter `async` ¶

iter(
    *,
    user_ids: StrList | None = None,
    organization_ids: StrList | None = None,
    project_ids: StrList | None = None,
    order_by: str | None = None,
    created_at_gte: str | None = None,
    created_at_gt: str | None = None,
    created_at_lte: str | None = None,
    created_at_lt: str | None = None,
    updated_at_gte: str | None = None,
    updated_at_gt: str | None = None,
    updated_at_lte: str | None = None,
    updated_at_lt: str | None = None,
    limit: int | None = None
) -> AsyncIterator[Chat]

Async analogue of iter.

get `async` ¶

get(
    chat_id: str,
    *,
    after_id: str | None = None,
    before_id: str | None = None,
    limit: int | None = None
) -> ChatMessagesPage

Async analogue of get.

iter_messages `async` ¶

iter_messages(
    chat_id: str, *, limit: int | None = None
) -> AsyncIterator[Message]

Async analogue of iter_messages.

delete `async` ¶

delete(chat_id: str) -> None

Async analogue of delete.

Chats¶

chats ¶

Chat dataclass ¶

from_dict classmethod ¶

Message dataclass ¶

from_dict classmethod ¶

ChatMessagesPage dataclass ¶

from_dict classmethod ¶

Chats ¶

list ¶

iter ¶

get ¶

iter_messages ¶

delete ¶

AsyncChats ¶

list async ¶

iter async ¶

get async ¶

iter_messages async ¶

delete async ¶

Chat `dataclass` ¶

from_dict `classmethod` ¶

Message `dataclass` ¶

from_dict `classmethod` ¶

ChatMessagesPage `dataclass` ¶

from_dict `classmethod` ¶

list `async` ¶

iter `async` ¶

get `async` ¶

iter_messages `async` ¶

delete `async` ¶