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

# API overview

> Base URL, versioning, authentication, and conventions for the TrueMath REST API.

The TrueMath API lets you run calculations and read domains over HTTP from your own application or agent.

## Base URL

```http theme={null}
https://api.truemath.ai
```

All endpoints are versioned under `/v1`. Requests and responses are JSON; send `Content-Type: application/json` on requests with a body.

## Authentication

Every request is authenticated with a bearer API key:

```http theme={null}
Authorization: Bearer tm_live_...
```

See [Authentication](https://docs.truemath.ai/api/authentication.md) for how to obtain and use a key.

## Endpoints

| Method | Path | Purpose |
| - | - | - |
| `POST` | `/v1/calculate` | [Run a calculation](https://docs.truemath.ai/api/calculate.md) |
| `GET` | `/v1/conversations` | [List conversations](https://docs.truemath.ai/api/conversations.md) |
| `GET` | `/v1/conversations/:id` | [Retrieve a conversation's history](https://docs.truemath.ai/api/conversations.md) |
| `GET` | `/v1/conversations/:id/context` | [Retrieve all scenarios](https://docs.truemath.ai/api/scenario-context.md) |
| `GET` | `/v1/conversations/:id/context/:scenario_id` | [Retrieve one scenario](https://docs.truemath.ai/api/scenario-context.md) |
| `GET` | `/v1/domains` | [List published domains](https://docs.truemath.ai/api/domains.md) |
| `GET` | `/v1/domains/:id/variables` | [List a domain's variables](https://docs.truemath.ai/api/domains.md) |
| `GET` | `/v1/domains/:id/activities` | [List a domain's activities](https://docs.truemath.ai/api/domains.md) |

## Conventions

* **Identifiers** — domains, conversations, and messages are identified by UUIDs.
* **Keys** — a [variable](https://docs.truemath.ai/concepts/variables.md) is referenced by its short key, which the API returns on each variable, and a UUID. Domains, activities, conversations, and messages are referenced by UUID. UUIDs are static; keys can change.
* **Values carry units** — a value is returned as a string with its unit included, for example `"375000 USD"` or `"30 yr"`. See [Units and precision](https://docs.truemath.ai/concepts/units-and-precision.md).
* **Provenance** — each returned variable reports a `source` and whether it was carried forward. See [Provenance](https://docs.truemath.ai/concepts/provenance.md).
* **Timestamps** — ISO 8601.
* **Published only** — the API returns and calculates against [published](https://docs.truemath.ai/concepts/versioning.md) domains.
* **Response version** — a `version` field reports the shape of the response body. See [Response version](#response-version).

## Response version

A `version` field reports the **shape of the response body** — which keys are present and what they are named. It is at the top level of a [calculation](https://docs.truemath.ai/api/calculate.md) result and of each [domain](https://docs.truemath.ai/api/domains.md) read response, and on each message in a [conversation's history](https://docs.truemath.ai/api/conversations.md).

```json theme={null}
{
  "domains": [ { "id": "6ba7b810-...", "title": "Mortgage", "description": "..." } ],
  "version": 2
}
```

It is not the version of the API: the path stays `/v1` whatever this number is.

`version` is `2` today. A different number means the body's shape is not the one your code was written against, so read it and treat an unfamiliar value as a signal to check your parsing.

A calculation result carries a second `version` unrelated to this one. `parsed_json.version` reports the shape of the parsed input inside `parsed_json`, not of the response body around it. It is also `2` today, and the two are versioned separately. See [Calculate](https://docs.truemath.ai/api/calculate.md#response).

## Errors

Transport-level problems use standard HTTP status codes with a JSON error body; calculation problems are returned in a successful response with a status of `error`. See [Errors](https://docs.truemath.ai/api/errors.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.