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

​
Base URL

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:
See Authentication for how to obtain and use a key.

​
Endpoints

​
Conventions

  • Identifiers — domains, conversations, and messages are identified by UUIDs.
  • Keys — a variable 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.
  • Provenance — each returned variable reports a source and whether it was carried forward. See Provenance.
  • Timestamps — ISO 8601.
  • Published only — the API returns and calculates against published domains.
  • Response version — a version field reports the shape of the response body. See 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 result and of each domain read response, and on each message in a conversation’s history.
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.

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