Domains

These endpoints let you discover the domains available to your account and inspect their variables and activities. Domains, activities, and variables are addressed by id. Only published domains are returned. Each response carries a top-level version reporting the shape of its body, currently 2. It is not the /v1 API version — see Response version.

List domains

GET /v1/domains

{
  "domains": [
    { "id": "6ba7b810-...", "title": "Mortgage", "description": "..." }
  ],
  "version": 2
}

List a domain’s variables

GET /v1/domains/:id/variables

Returns the domain and its variables, each with its default value, the two fields needed to render it, and its suggested units. Useful for building structured text and input forms.

{
  "domain": { "id": "6ba7b810-...", "title": "Mortgage", "description": "..." },
  "variables": [
    {
      "id": "...",
      "key": "home_price",
      "title": "Home price",
      "description": "...",
      "default_value": "0 USD",
      "kind": "number",
      "format": "decimals_2",
      "unit_options": ["USD"]
    }
  ],
  "version": 2
}

Each variable carries exactly these fields: id, key, title, description, default_value, kind, and format, plus unit_options when the variable has any.

Field	Type	Description
`default_value`	string \| array	The value applied when none is provided in a calculation, written as a combined `"value unit"` string (see Provenance), or an empty string when the variable has no default. A table variable’s default is an array of combined cell strings.
`kind`	string	`number`, `percent`, `no_separator`, `duration`, `date`, `datetime`, `time`, `table`, `bar_chart`, or `pie_chart`.
`format`	string \| null	How the value is shown, from the vocabulary its `kind` takes. `null` for `table`, `bar_chart`, and `pie_chart`, whose formats are set per column or per series — read those from `/activities`.
`unit_options`	array \| absent	The suggested units for this variable, in the author’s order, the first being its primary unit. A suggestion, not a restriction: any unit TrueMath recognizes is still accepted, and the list may not include the unit a value uses. Absent, not empty, when there are none. Always absent on any kind but `number` and `no_separator`; a table variable has one list per column, readable from `/activities`.

Rendering a default value

default_value is not self-describing, so pair it with kind and format:

A percent stores a decimal — 0.06 renders as 6%.
A duration, date, datetime, or time stores a count of seconds. Render it with a UTC-pinned formatter; the notes under Dates and durations apply to a default verbatim.
A default of one of those four kinds may instead be the literal word today or now, which stands for the moment the calculation runs rather than the moment the domain was authored. See today and now as defaults.

Reading unit options

The list is the units the author suggests for this variable, in their order, and the first one is the primary unit — the one to offer first. Everything else is up to you: how you show a unit, whether people pick one from a menu or some other way, and how a compound unit such as USD/ft² looks next to a value. Two things to know before you build on it:

The list says nothing about any particular value. An author is not required to include the unit the default value uses, and a value you already hold can have any unit at all. A unit is part of the value, so read it from the value.
Nothing is enforced. A value whose unit is outside the list is accepted like any other, and dimensional validation is unchanged, so shortening a list never breaks a caller that sends something else.

Read the list here or from /activities, where a table variable’s columns each have their own in display_metadata.table.columns[].

List a domain’s activities

GET /v1/domains/:id/activities

Returns a domain’s definition: its activities — each with its equation, state, and the variables it references — and its variables with their stored display configuration. This describes how the domain is configured, in contrast to POST /v1/calculate, which returns computed values with a render-ready display for each. The two carry similar display information in different shapes — see Display configuration vs. display.

{
  "domain": {
    "id": "6ba7b810-...",
    "title": "Mortgage",
    "description": "...",
    "has_draft": false,
    "has_published": true
  },
  "activities": [
    {
      "id": "...",
      "title": "Monthly payment",
      "description": "...",
      "equation": "...",
      "state": "active",
      "variable_refs": [
        { "variable_id": "...", "calculable": true }
      ]
    }
  ],
  "variables": [
    {
      "id": "...",
      "key": "interest_rate",
      "title": "Interest rate",
      "description": "...",
      "default_value": "0",
      "kind": "percent",
      "display_metadata": {
        "number": { "format": "decimals_2" }
      }
    },
    {
      "id": "...",
      "key": "loan_term",
      "title": "Term",
      "description": "...",
      "default_value": "30 yr",
      "kind": "number",
      "unit_options": ["yr", "mo"],
      "display_metadata": {
        "number": { "format": "decimals_0" }
      }
    }
  ],
  "version": 2
}

Domain — the published domain, with flags for whether a draft and a published version exist:

Field	Type	Description
`id`	UUID	The domain.
`title` / `description`	string	Human- and agent-readable labels.
`has_draft`	boolean	Whether an unpublished draft exists.
`has_published`	boolean	Whether a published version exists.

Activities — one entry per activity:

Field	Type	Description
`id`	UUID	The activity.
`title` / `description`	string	Labels.
`equation`	string	The activity’s equation.
`state`	string	`active` or `disabled`. Deleted activities are not returned.
`variable_refs[]`	array	The variables the activity references, in the order the author set — each a `variable_id` with whether it is `calculable`.

Variables — one entry per variable, in definition form:

Field	Type	Description
`id`	UUID	The variable.
`key`	string	The author-chosen name used in equations and in input — `home_price`, `loan_term`.
`title` / `description`	string	Labels.
`default_value`	string \| array	The value applied when none is provided, as a combined `"value unit"` string, or an empty string when the variable has no default. A table variable’s default is an array of combined cell strings.
`kind`	string	What the value is: `number`, `percent`, `no_separator`, `duration`, `date`, `datetime`, `time`, `table`, `bar_chart`, or `pie_chart`. The four time kinds are described in Authoring dates and durations.
`unit_options`	array \| absent	The suggested units for this variable, in the author’s order, the first being its primary unit. Absent when there are none, and always absent on any kind but `number` and `no_separator`. A `table` variable’s columns each have their own inside `display_metadata.table.columns[]`.
`display_metadata`	object	The variable’s display configuration (see below).

display_metadata

display_metadata holds the variable’s display configuration under a single key naming its structural type — number (for number, percent, and no_separator), table, bar_chart, or pie_chart:

"display_metadata": {
  "number": { "format": "decimals_2" }
}

The inner object carries the same fields as the matching display object in a calculation result — format for a scalar; start_row_index, columns, and rows for a table; series or slice configuration for a chart. Unlike a calculation result’s display, the definition is not normalized: optional fields may be absent rather than filled with defaults. A table column is the exception. Each entry of columns is a name, a kind, a format, and, when the author set any, its own unit_options:

"display_metadata": {
  "table": {
    "start_row_index": 1,
    "columns": [
      { "name": "Payment", "kind": "number", "format": "decimals_2", "unit_options": ["USD"] }
    ],
    "rows": { "names": [] }
  }
}

The number key holds the configuration for every scalar type, the four time kinds included, so a date variable’s format token is at display_metadata.number.format:

"display_metadata": {
  "number": { "format": "date_med" }
}

Display configuration vs. display

The same variable’s formatting appears in two shapes, and kind does not cover the same ground in each:

	`/domains/:id/activities` (definition)	`/calculate` (result)
Structure	nested under the type key: `display_metadata.<type>.{...}`	flat: `display.{...}`
Type field	`kind` covers the whole variable, `table`, `bar_chart`, and `pie_chart` included	split into `data_type` (structural) and `kind` (scalar only)
Unit options	`unit_options` on the variable itself, beside `kind`, and one list per column in `display_metadata.table.columns[]`	not included
Completeness	as stored — optional fields may be absent	normalized — defaults filled, empty collections shown as `{}`

That split is the gotcha: in a definition kind can be table, but in a result kind is only ever one of the scalar kinds and the structural shape is in data_type. unit_options runs the other way: it is part of the definition and not part of a result.

Introduction

Quickstart

Concepts

Domain Library

Playground

Authoring Domains

Data Types

Units

Function Library

API Reference

Resources

List domains

List a domain’s variables

Rendering a default value

Reading unit options

List a domain’s activities

display_metadata

Display configuration vs. display

​List domains

​List a domain’s variables

​Rendering a default value

​Reading unit options

​List a domain’s activities

​display_metadata

​Display configuration vs. display

List domains

List a domain’s variables

Rendering a default value

Reading unit options

List a domain’s activities

display_metadata

Display configuration vs. display