> For the complete documentation index, see [llms.txt](https://docs.sumble.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sumble.com/api/conversations.md).

# Conversation history

Read your Ask Sumble conversations through the API or MCP. Both operations are free. They return only conversations you own, even if you can read or participate in other conversations shared through the web app.

## List conversations

`GET /v9/conversations?page=1` returns up to 30 conversations, most recently updated first. Each entry includes its `id`, `title`, `created_at`, `updated_at`, `message_count`, `turn_count`, and a `sumble_url` to open it in the web app. A new conversation can have a null title and no messages. Turn counts include user messages still waiting for an answer.

Pass the response's `next_page` as `page` to continue. A null `next_page` means there are no more results. Page numbers start at 1. Conversations updated between requests can move between pages.

## List your Ask Sumble conversations

> Return 30 conversations per page, most recently updated first. Free.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"ConversationListResponse":{"properties":{"conversations":{"items":{"$ref":"#/components/schemas/ConversationSummary"},"type":"array","title":"Conversations"},"next_page":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Page","description":"Pass this as page to read more; null means there are no more results."}},"type":"object","required":["conversations","next_page"],"title":"ConversationListResponse"},"ConversationSummary":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"sumble_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Sumble Url","description":"Open this conversation in the Sumble web app."},"message_count":{"type":"integer","title":"Message Count"},"turn_count":{"type":"integer","title":"Turn Count","description":"Number of user messages, including pending turns."}},"type":"object","required":["id","title","created_at","updated_at","sumble_url","message_count","turn_count"],"title":"ConversationSummary"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/conversations":{"get":{"tags":["conversations"],"summary":"List your Ask Sumble conversations","description":"Return 30 conversations per page, most recently updated first. Free.","operationId":"list_conversations__api_version__conversations_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1,"title":"Page"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## Read a conversation

`GET /v9/conversations/{conversation_id}` returns the same metadata and the transcript, oldest message first. It reads the saved transcript, so messages remain available after the assistant's working context expires or is shortened.

Long transcripts come back in pages of about 60,000 characters of message text. Pass the response's `next_message_offset` as `message_offset` to read the next page. A null `next_message_offset` means you have the last message. A single message longer than that limit comes back whole, on a page of its own.

Each message includes its text, role, timestamp, and any generated files. File entries include a filename, file id, and `download_url` when a standalone download page is available. When `download_url` is null, open the conversation's `sumble_url` and use its file download controls. These links require the user to sign in to Sumble. Files can expire independently of the transcript. Uploaded attachments are recorded by name only; their contents are not retained.

Where available, messages include `credits_charged`, `credits_refunded`, and `elapsed_seconds`. `credits_charged` is the net charge after refunds. Null values mean no accounting or timing record exists for that message. Reading a conversation does not charge these credits again.

A missing conversation or one owned by another user returns 404.

## Read one of your Ask Sumble conversations

> Read the durable transcript, generated files, and credit stats. Free.\
> \
> Returns messages from \`message\_offset\` on, up to about 60,000 characters of\
> message text. Pass \`next\_message\_offset\` back to read the rest.\
> \
> Only the owner can read a conversation here, including when it is shared\
> in the web app. Missing conversations and other users' conversations return\
> the same 404. Historical messages may have no credit accounting.

```json
{"openapi":"3.1.0","info":{"title":"Sumble API","version":"v9"},"servers":[{"url":"https://api.sumble.com"}],"security":[{"api_token":[]}],"components":{"securitySchemes":{"api_token":{"type":"http","scheme":"bearer"}},"schemas":{"ConversationDetailResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"updated_at":{"type":"string","format":"date-time","title":"Updated At"},"sumble_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Sumble Url","description":"Open this conversation in the Sumble web app."},"message_count":{"type":"integer","title":"Message Count"},"turn_count":{"type":"integer","title":"Turn Count","description":"Number of user messages, including pending turns."},"messages":{"items":{"$ref":"#/components/schemas/ConversationMessage"},"type":"array","title":"Messages"},"next_message_offset":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Next Message Offset","description":"Pass this as message_offset to read the rest of the transcript; null means this page reaches the last message."}},"type":"object","required":["id","title","created_at","updated_at","sumble_url","message_count","turn_count","messages","next_message_offset"],"title":"ConversationDetailResponse"},"ConversationMessage":{"properties":{"turn_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Turn Id"},"role":{"type":"string","title":"Role"},"text":{"type":"string","title":"Text"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"files":{"items":{"$ref":"#/components/schemas/ConversationFile"},"type":"array","title":"Files"},"attachments":{"items":{"type":"string"},"type":"array","title":"Attachments","description":"Names of uploaded attachments. Their contents are not retained."},"credits_charged":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Charged","description":"Net credits charged after refunds; null if accounting is unavailable."},"credits_refunded":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Credits Refunded"},"elapsed_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Elapsed Seconds"}},"type":"object","required":["turn_id","role","text","created_at","files","attachments","credits_charged","credits_refunded","elapsed_seconds"],"title":"ConversationMessage"},"ConversationFile":{"properties":{"file_id":{"type":"string","title":"File Id"},"filename":{"type":"string","title":"Filename"},"download_url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Download Url","description":"Authenticated download page when available. Otherwise open the conversation's sumble_url and use its file download controls."}},"type":"object","required":["file_id","filename","download_url"],"title":"ConversationFile"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v9/conversations/{conversation_id}":{"get":{"tags":["conversations"],"summary":"Read one of your Ask Sumble conversations","description":"Read the durable transcript, generated files, and credit stats. Free.\n\nReturns messages from `message_offset` on, up to about 60,000 characters of\nmessage text. Pass `next_message_offset` back to read the rest.\n\nOnly the owner can read a conversation here, including when it is shared\nin the web app. Missing conversations and other users' conversations return\nthe same 404. Historical messages may have no credit accounting.","operationId":"get_conversation__api_version__conversations__conversation_id__get","parameters":[{"name":"conversation_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Conversation Id"}},{"name":"message_offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Message Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationDetailResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## MCP

Use `ListConversations` to find a conversation by title and date, then pass its id to `GetConversation` to read it. Both tools are free.
