> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truemath.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conversations

> List conversations and retrieve a conversation's full message history, including the results and errors of each calculation.

A [conversation](/concepts/scenarios) holds the sequence of calculations you run together, across one or more scenarios. These endpoints let you list conversations and read the full history of one.

## List conversations

```http theme={null}
GET /v1/conversations
```

Returns conversations most-recently-active first.

| Query param      | Type    | Default | Description                                          |
| ---------------- | ------- | ------- | ---------------------------------------------------- |
| `limit`          | integer | 20      | Page size, 1–100.                                    |
| `starting_after` | UUID    | —       | Cursor — pass the previous response's `next_cursor`. |

```json theme={null}
{
  "conversations": [
    {
      "id": "550e8400-...",
      "title": "What is the monthly payment?",
      "notes": null,
      "domain_id": "7b1e...",
      "last_activity_at": "2026-06-01T17:04:22Z"
    }
  ],
  "next_cursor": "550e8400-..."
}
```

| Field              | Type           | Description                                                                                                                                   |
| ------------------ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | UUID           | The conversation.                                                                                                                             |
| `title`            | string \| null | Human-friendly title, auto-set from the conversation's first message and editable in the app.                                                 |
| `notes`            | string \| null | Freeform user notes, set in the app.                                                                                                          |
| `domain_id`        | UUID \| null   | The conversation's [domain](/concepts/domains), set from its first message. `null` for older conversations created before this field existed. |
| `last_activity_at` | ISO 8601       | When the conversation was last active.                                                                                                        |

When `next_cursor` is `null`, there are no more pages. See [Limits](/api/limits#pagination).

## Retrieve a conversation

```http theme={null}
GET /v1/conversations/:id
```

Returns the conversation's scenario position and its messages in chronological order, oldest first. Each message mirrors the shape returned by [`POST /v1/calculate`](/api/calculate): `completed` messages include `results`, `error` messages include `errors`, and `in_progress` messages omit both.

```json theme={null}
{
  "conversation_id": "550e8400-...",
  "title": "What is the monthly payment?",
  "notes": null,
  "domain": { "id": "7b1e...", "title": "Mortgage", "description": "..." },
  "current_scenario_index": 2,
  "last_scenario_index": 2,
  "last_activity_at": "2026-06-01T17:06:30Z",
  "messages": [
    {
      "message_id": "0b7e...e1",
      "idempotency_key": "a1b2c3",
      "status": "completed",
      "source": "api",
      "input_format": "natural_language",
      "domain": { "id": "...", "title": "Mortgage", "description": "..." },
      "natural_language": "What is the monthly payment on a $400,000 loan at 6% over 30 years?",
      "parsed_json": {
        "inputs": [
          { "key": "loan_amount", "value": "400000 USD" },
          { "key": "interest_rate", "value": "6%" },
          { "key": "loan_term", "value": "30 yr" }
        ],
        "calculate": { "key": "monthly_payment", "unit": null },
        "scenario": "new"
      },
      "structured_text": null,
      "created_at": "2026-06-01T17:04:20Z",
      "updated_at": "2026-06-01T17:04:22Z",
      "results": { "...": "see POST /v1/calculate" },
      "version": 1
    },
    {
      "message_id": "1c8f...a2",
      "idempotency_key": null,
      "status": "error",
      "source": "api",
      "input_format": "structured",
      "domain": { "id": "...", "title": "Mortgage", "description": "..." },
      "structured_text": null,
      "created_at": "2026-06-01T17:05:01Z",
      "updated_at": "2026-06-01T17:05:01Z",
      "errors": [ { "...": "see Errors" } ],
      "version": 1
    },
    {
      "message_id": "2d9a...b3",
      "idempotency_key": "d4e5f6",
      "status": "in_progress",
      "source": "api",
      "input_format": "natural_language",
      "domain": { "id": "...", "title": "Mortgage", "description": "..." },
      "structured_text": null,
      "created_at": "2026-06-01T17:06:30Z",
      "updated_at": "2026-06-01T17:06:30Z",
      "version": 1
    }
  ]
}
```

| Field                    | Type            | Description                                                                                                |
| ------------------------ | --------------- | ---------------------------------------------------------------------------------------------------------- |
| `conversation_id`        | UUID            | The conversation.                                                                                          |
| `title`                  | string \| null  | Human-friendly title, auto-set from the conversation's first message and editable in the app.              |
| `notes`                  | string \| null  | Freeform user notes, set in the app.                                                                       |
| `domain`                 | object \| null  | The conversation's [domain](/concepts/domains) — `id`, `title`, `description`. Set from the first message. |
| `current_scenario_index` | integer \| null | The [scenario](/concepts/scenarios) currently in focus, or `null` if none.                                 |
| `last_scenario_index`    | integer \| null | The most recently created scenario, or `null` if none.                                                     |
| `last_activity_at`       | ISO 8601        | When the conversation was last active.                                                                     |
| `messages`               | array           | The messages, oldest first.                                                                                |

Each message carries the same fields as a [`POST /v1/calculate`](/api/calculate) response, except that `conversation_id` is lifted to the top level:

| Field                       | Type           | Description                                                                                                                                                                                                    |
| --------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message_id`                | UUID           | This message.                                                                                                                                                                                                  |
| `idempotency_key`           | string \| null | The key sent with the request, echoed back.                                                                                                                                                                    |
| `status`                    | string         | `completed`, `error`, or `in_progress`.                                                                                                                                                                        |
| `source`                    | string         | `api` or `chat`.                                                                                                                                                                                               |
| `input_format`              | string         | `natural_language`, `structured`, or `json`.                                                                                                                                                                   |
| `domain`                    | object \| null | The domain — `id`, `title`, `description`.                                                                                                                                                                     |
| `natural_language`          | string \| null | The natural-language reading. Present only when `input_format` is `natural_language` and `status` is `completed`; omitted otherwise.                                                                           |
| `parsed_json`               | object         | The parsed input object (same shape as a [JSON request](/concepts/input-formats#json)). Present only when `input_format` is `natural_language` or `json` and `status` is `completed`; omitted otherwise.       |
| `structured_text`           | string \| null | The result as [structured text](/concepts/input-formats#structured-text). Carries the result for a `structured` request and is `null` for `natural_language` and `json`; `null` until `status` is `completed`. |
| `created_at` / `updated_at` | ISO 8601       | When the message was created and last updated.                                                                                                                                                                 |
| `results`                   | object         | Present when `status` is `completed`. See [Calculate](/api/calculate#completed).                                                                                                                               |
| `errors`                    | array          | Present when `status` is `error`. See [Errors](/api/errors#calculation-errors).                                                                                                                                |
| `version`                   | integer        | Response data-structure version, separate from the `/v1` API version.                                                                                                                                          |

A request for a conversation that does not exist returns `404`; see [Errors](/api/errors#transport-errors) for transport-level failures.

<Note>
  `title` and `notes` are read-only over the API. They are set in the TrueMath app — `title` is auto-generated from the first message and editable there, and `notes` is entered by the user. There is no API endpoint to edit them.
</Note>

<Note>
  To read the resolved state of a scenario — its domains, activities, and variables — rather than the message history, use [Scenario context](/api/scenario-context).
</Note>