# Conversations

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

Source: https://maincode.com/docs/python-client-sdk-conversations
Section: Client SDK · Matilda documentation

---

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

## `conversations.list(...)`

Lists conversations with pagination.

```python title="list.py"
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}`).