Calculate

POST /v1/calculate

Runs a calculation against a published domain. A calculation happens inside a conversation: omit conversation_id to start a new conversation, or pass one to continue an existing one.

Request

Field	Type	Required	Description
`domain_id`	UUID	Yes	The domain to calculate against.
`input_format`	string	No	`natural_language`, `structured`, `json`, or `automatic`. Optional — omit it, or pass `null` or `""`, to default to `automatic`. See Automatic detection.
`prompt`	string	Yes	The input — prose for `natural_language`, `key: value` lines for `structured`, or a JSON string for `json`. See Input formats.
`conversation_id`	UUID	No	Continue an existing conversation. Omit to start a new one.

Send an Idempotency-Key header to make a request safe to retry and to poll. Since natural language requests return immediately with 202 Accepted, an Idempotency Key is required to retrieve the final result. See Limits.

Natural language input

{
  "domain_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "input_format": "natural_language",
  "prompt": "What is the monthly payment on a $400,000 loan at 6% over 30 years?"
}

Structured input

Structured input is a set of key: value lines — one variable per line — plus a calculate: line naming the variable to solve for. For the full grammar — values, units, tables, scenario selectors, and how omitted lines are inferred — see Input formats.

{
  "domain_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "input_format": "structured",
  "prompt": "home_price: $500,000\ndown_payment: $100,000\ninterest_rate: 6.5%\nloan_term: 30 yr\ncalculate: monthly_payment"
}

JSON input

A JSON request sets input_format to json and passes a JSON string as prompt. Like structured text, it involves no language model and runs synchronously — the result returns in the same response. For the full object — inputs, calculate, scenario, and value conventions — see Input formats.

{
  "domain_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "input_format": "json",
  "prompt": "{\"inputs\":[{\"key\":\"home_price\",\"value\":\"500000 USD\"},{\"key\":\"down_payment\",\"value\":\"100000 USD\"},{\"key\":\"interest_rate\",\"value\":\"6.5%\"},{\"key\":\"loan_term\",\"value\":\"30 yr\"}],\"calculate\":{\"key\":\"monthly_payment\",\"unit\":null},\"scenario\":\"new\"}"
}

A prompt that parses as JSON but does not match the schema returns input.invalid_input_schema; a prompt that is not valid JSON returns the transport error error_invalid_json.

Automatic detection

Set input_format to automatic — or leave it out, or pass null or "" — to let TrueMath determine from the prompt whether it is natural language, structured text, or JSON, and process it accordingly. This is the default when the field is absent.

{
  "domain_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "prompt": "What is the monthly payment on a $400,000 loan at 6% over 30 years?"
}

Because the detected format governs processing, the same request behavior applies once it is resolved — a prompt detected as natural_language is processed asynchronously, while one detected as structured or json runs synchronously. Specify input_format explicitly when you already know the format and want to skip detection.

Response

The response echoes the conversation, message, and request metadata, and reports its outcome with status. A completed or error outcome returns 200 OK; an asynchronous request that is still running returns 202 Accepted with status: "in_progress".

Field	Type	Description
`conversation_id`	UUID	The conversation this calculation belongs to.
`message_id`	UUID	This request’s message.
`idempotency_key`	string \| null	The key you sent, echoed back.
`status`	string	`completed`, `in_progress`, or `error`.
`source`	string	How the request was made — `api` or `chat`.
`input_format`	string	`natural_language`, `structured`, or `json`.
`natural_language`	string	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 — the 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. Always a key on a completed response: it carries the result for a `structured` request and is `null` for `natural_language` and `json`. `null` until `status` is `completed`.
`domain`	object \| null	The domain these results belong to — `id`, `title`, `description`.
`created_at` / `updated_at`	ISO 8601	When the message was created and last updated.
`results`	object	The calculation outcome. Present when `status` is `completed`.
`errors`	array	Calculation errors. Present when `status` is `error`.
`version`	integer	Response data-structure version, separate from the `/v1` API version.

The echo of your input depends on the format. A structured request returns its result as structured_text. A natural_language request returns the natural_language reading plus the parsed input as parsed_json. A json request returns the parsed input as parsed_json. structured_text is always a key on a completed response — null for natural_language and json — while natural_language and parsed_json are present only for the formats noted above and omitted otherwise.

Completed

A completed calculation returns status: "completed" and a results object: the action taken, the scenario indexes, the activities applied, and every variable with its value, provenance, and display format. results.calculated is the id of the variable that was solved for (null when action is fetch).

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": "0b7e...e1",
  "idempotency_key": "a1b2c3",
  "status": "completed",
  "source": "api",
  "input_format": "structured",
  "structured_text": "loan_amount: 400000 USD\nmonthly_payment: 2398.20 USD",
  "domain": { "id": "...", "title": "Mortgage", "description": "..." },
  "created_at": "2026-06-05T18:30:00Z",
  "updated_at": "2026-06-05T18:30:00Z",
  "results": {
    "action": "new",
    "scenario": { "original": 0, "current": 1 },
    "activities": [
      {
        "id": "...",
        "title": "Monthly payment",
        "description": "...",
        "equation": "...",
        "state": "published",
        "variables": [{ "id": "...", "calculable": true }]
      }
    ],
    "variables": [
      {
        "id": "...",
        "key": "loan_amount",
        "title": "Loan amount",
        "description": "...",
        "source": "user_input",
        "historical": false,
        "value": "400000 USD",
        "display": { "data_type": "number", "display_type": "number", "decimal_format": "decimals_2" }
      },
      {
        "id": "...",
        "key": "monthly_payment",
        "title": "Monthly payment",
        "description": "...",
        "source": "calculated",
        "historical": false,
        "value": "2398.20 USD",
        "display": { "data_type": "number", "display_type": "number", "decimal_format": "decimals_2" }
      }
    ],
    "calculated": "..."
  },
  "version": 1
}

Each variable’s key is its creator-defined variable name. source is user_input, calculated, or default_value, and historical indicates whether the value was carried forward from a prior scenario. value is a combined "value unit" string at full precision — the unit travels inside the value (see Units and precision). For a table, value is an array of such strings (nested for a 2-D table); see Tables. The scenario object reports the original scenario the calculation started from (0 starts a new scenario) and the current scenario the results belong to. action is one of new, extend, discard, or fetch — see Scenarios. When action is fetch, retrieve that scenario with GET /v1/conversations/:id/context.

Display formats

Each variable carries a display object. data_type selects its shape — number, table, bar_chart, or pie_chart — and the remaining fields depend on it. Two fields recur across shapes:

Field	Type	Values	Description
`display_type`	string	`number`, `no_separator`, `percent`	How a value is formatted. Currency is conveyed by the value’s unit, not here.
`decimal_format`	string	`decimals_0`–`decimals_9`, `decimals_float`	Decimal-precision code applied when formatting.

number — a scalar or unit value.

{ "data_type": "number", "display_type": "number", "decimal_format": "decimals_2" }

table — a grid with per-column formats and optional row names.

{
  "data_type": "table",
  "start_row_index": 1,
  "columns": [
    { "name": "Payment", "display_type": "number", "decimal_format": "decimals_2" }
  ],
  "rows": { "names": ["Year 1", "Year 2"] }
}

Field	Type	Description
`start_row_index`	integer	Index of the first row (tables are 1-indexed).
`columns[]`	array	Per-column format — each has `name`, `display_type`, and `decimal_format`.
`rows.names`	string[]	Optional row labels.

bar_chart — a table presented as a bar chart.

{
  "data_type": "bar_chart",
  "series_by": "columns",
  "stacked": false,
  "x_axis": { "title": "Year" },
  "labels": { "source": "index", "start_series_index": 1 },
  "series": [
    { "name": "Payment", "display_type": "number", "decimal_format": "decimals_2" }
  ]
}

Field	Type	Values	Description
`series_by`	string	`columns`, `rows`	Whether each series is a column or a row of the table.
`stacked`	boolean		Whether series are stacked.
`x_axis.title`	string		X-axis label.
`labels.source`	string	`index`, `first_series`	Where bar labels come from.
`labels.start_series_index`	integer		First series used for labels.
`series[]`	array		Per-series format — each has `name`, `display_type`, and `decimal_format`.

pie_chart — a table presented as a pie chart.

{
  "data_type": "pie_chart",
  "display_type": "number",
  "decimal_format": "decimals_2",
  "slices": { "names": ["Principal", "Interest"] }
}

Field	Type	Description
`slices.names`	string[]	Optional slice labels.

Chart scaling

When a bar_chart or pie_chart is built from a table column whose cells carry different units of the same dimension — for example 3 ft, 4 in, 5 yd — the chart variable carries an optional scale companion: the same magnitudes restated in one common unit, so a client can draw bars and slices to honest geometry. value is unchanged — it remains the authoritative data and still drives labels and tooltips. These fields sit on the variable, alongside value and display, and are present only when relevant.

Field	Type	When present	Description
`scale`	number[]	Chart cells share a dimension but span two or more units.	The magnitudes restated in one common unit, in the same shape as `value`. Use for bar heights and slice angles; `null` entries mirror empty cells.
`scale_unit`	string	With `scale`.	The common unit the `scale` magnitudes are in — use it as the axis unit.
`scale_incompatible`	boolean	Chart cells span different dimensions.	`true` when the column mixes dimensions — for example length and mass — and has no common axis, so it cannot be charted.
`scale_types`	string[]	With `scale_incompatible`.	The conflicting unit type names, such as `["Length", "Mass"]`.

A chart variable is in exactly one of three states:

Scaled — scale and scale_unit are present. Plot from scale, label the axis with scale_unit, and show the original value cell in tooltips.
Incompatible — scale_incompatible and scale_types are present. There is no common axis; render a short message instead of a chart.
Neither — no scale fields. The column is a single unit or unitless; plot the numeric part of each value cell directly, with the first cell’s unit as the axis unit.

The common unit is the first cell’s unit. scale values are full precision — format them with the variable’s display decimal settings, the same as value.

{
  "key": "chart",
  "value": ["3 ft", "4 in", "5 yd"],
  "display": { "data_type": "bar_chart" },
  "scale": [3, 0.3333333333333333, 15],
  "scale_unit": "ft"
}

The bars sit at 3, 0.333, and 15 on a ft axis, while the second bar’s tooltip reads 4 in — the original authored value, not 0.333 ft. When the cells span different dimensions, no chart is drawn:

{
  "key": "chart",
  "value": ["3 ft", "4 kg"],
  "display": { "data_type": "bar_chart" },
  "scale_incompatible": true,
  "scale_types": ["Length", "Mass"]
}

In progress

Natural-language requests will be processed asynchronously; structured-text and JSON requests run synchronously and never return in_progress. When a natural-language request is still running, the API responds with 202 Accepted, status: "in_progress" and no results:

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": "0b7e...e1",
  "status": "in_progress",
  "source": "api",
  "input_format": "natural_language",
  "domain": { "id": "...", "title": "Mortgage", "description": "..." },
  "created_at": "2026-06-05T18:30:00Z",
  "updated_at": "2026-06-05T18:30:00Z",
  "version": 1
}

To get the result for natural language requests, re-post the same body with the same Idempotency-Key until status is completed or error. Leave a 1–2 second gap between retries. This could take multiple retries but rarely more than 20 total. You can also poll the conversation with GET /v1/conversations/:id.

Error

A calculation that cannot complete returns status: "error" with an errors array. Each entry has a code and message, plus conditionally included args, offset, and missing fields (present only when the error uses them).

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": "0b7e...e1",
  "status": "error",
  "errors": [
    { "code": "input.incompatible_units", "message": "The unit '%arg0%' and the unit '%arg1%' are not compatible", "args": ["m", "in²"] }
  ],
  "version": 1
}

See Errors for what args, offset, and missing contain, and the full list of calculation error codes.

Transport errors

Problems with the request itself — rather than with the calculation — return a 4xx or 5xx status and a single error object:

{ "error": { "code": "...", "message": "...", "params": null } }

Status	Meaning
`400`	Invalid JSON or malformed structure.
`401`	Missing or invalid credentials.
`403`	API key disabled.
`409`	Idempotency conflict — same key reused with a different body.
`422`	Semantically invalid input, such as a missing required field.
`5xx`	Unexpected server failure.

Introduction

Quickstart

Concepts

Domain Library

Playground

Authoring Domains

Data Types

Units

Function Library

API Reference

Resources

Request

Natural language input

Structured input

JSON input

Automatic detection

Response

Completed

Display formats

Chart scaling

In progress

Error

Transport errors

​Request

​Natural language input

​Structured input

​JSON input

​Automatic detection

​Response

​Completed

​Display formats

​Chart scaling

​In progress

​Error

​Transport errors

Request

Natural language input

Structured input

JSON input

Automatic detection

Response

Completed

Display formats

Chart scaling

In progress

Error

Transport errors