> ## 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](/api/authentication) for how to obtain and use a key.

## Endpoints

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

## Conventions

* **Identifiers** — domains, conversations, and messages are identified by UUIDs.
* **Keys** — a [variable](/concepts/variables) 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](/concepts/units-and-precision).
* **Provenance** — each returned variable reports a `source` and whether it was carried forward. See [Provenance](/concepts/provenance).
* **Timestamps** — ISO 8601.
* **Published only** — the API returns and calculates against [published](/concepts/versioning) domains.

## 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](/api/errors).