Conversations

A conversation 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

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`.

{
  "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, 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.

Retrieve a conversation

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: completed messages include results, error messages include errors, and in_progress messages omit both.

{
  "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 — `id`, `title`, `description`. Set from the first message.
`current_scenario_index`	integer \| null	The scenario 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 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). 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. 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.
`errors`	array	Present when `status` is `error`. See 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 for transport-level failures.

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.

To read the resolved state of a scenario — its domains, activities, and variables — rather than the message history, use Scenario context.

Introduction

Quickstart

Concepts

Domain Library

Playground

Authoring Domains

Data Types

Units

Function Library

API Reference

Resources

List conversations

Retrieve a conversation

​List conversations

​Retrieve a conversation

List conversations

Retrieve a conversation