Client SDK · State and data

Conversations.

List, retrieve, rename, and rate the threads behind a conversation_id.

Conversation resources return plain dict objects using the server's camelCase wire keys.

`conversations.list(...)`

Lists conversations with pagination.

Python

async def main():
    async with MatildaClient(token="...") as client:
        result = await client.conversations.list(limit=20, offset=0)
        for conv in result["conversations"]:
            print(f"{conv['id']}: {conv['title']} (updated {conv['updatedAt']})")

Field	type	description
limit	int \| None	Maximum number of conversations to return.
offset	int \| None	Pagination offset.

Returns a dict:

Python

# ConversationListResponse:
{
    "conversations": [
        {
            "id": "conv-123",
            "userId": "user-1",
            "title": "My chat",
            "createdAt": "2026-08-18T10:30:00.000Z",
            "updatedAt": "2026-08-18T11:00:00.000Z",
        }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0,
}

`conversations.retrieve(conversation_id)`

Retrieves a full conversation thread with all messages.

Python

conv = await client.conversations.retrieve("conv-123")
for msg in conv["messages"]:
    print(f"[{msg['role']}] {msg['content']}")

Returns a dict — the summary shape above plus a messages list.

`conversations.update(conversation_id, *, title=...)`

Updates a conversation's metadata (currently only title).

Python

await client.conversations.update("conv-123", title="My Chat About AI")

Field	type	description
conversation_id	str	The conversation to update.
title	str	The new title.

Returns None.

`conversations.set_message_feedback(conversation_id, message_id, feedback)`

Sets thumbs-up or thumbs-down feedback on a specific message.

Python

await client.conversations.set_message_feedback("conv-123", "msg-456", "positive")

Field	type	description
conversation_id	str	The conversation containing the message.
message_id	str	The message to rate.
feedback	'positive' \| 'negative'	The feedback value.

Returns a dict (e.g. {"ok": True}).