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

# Domains

> List the published domains available to your account, and read a domain's variables and activities.

These endpoints let you discover the [domains](/concepts/domains) available to your account and inspect their [variables](/concepts/variables) and [activities](/concepts/activities). Only [published](/concepts/versioning) domains are returned.

## List domains

```http theme={null}
GET /v1/domains
```

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

## List a domain's variables

```http theme={null}
GET /v1/domains/:id/variables
```

Returns the domain and its variables, each with a default value and data type. Useful for building [structured text](/concepts/input-formats#structured-text).

```json theme={null}
{
  "domain": { "id": "6ba7b810-...", "key": "dm_8a3f2c9b1d4e6f0a7b5c", "title": "Mortgage", "description": "..." },
  "variables": [
    {
      "id": "...",
      "key": "home_price",
      "title": "Home price",
      "description": "...",
      "default_value": "0 USD",
      "data_type": "number"
    }
  ],
  "version": 1
}
```

`default_value` is the value applied when none is provided in a calculation, written as a combined `"value unit"` string (see [Provenance](/concepts/provenance)), or an empty string when the variable has no default. `data_type` is one of `number`, `table`, `bar_chart`, or `pie_chart`.

## List a domain's activities

```http theme={null}
GET /v1/domains/:id/activities
```

Returns a domain's **definition**: its [activities](/concepts/activities) — each with its equation, state, and the [variables](/concepts/variables) it references — and its variables with their stored display configuration. This describes how the domain is *configured*, in contrast to [`POST /v1/calculate`](/api/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](#display-configuration-vs-display).

```json theme={null}
{
  "domain": {
    "id": "6ba7b810-...",
    "key": "dm_8a3f2c9b1d4e6f0a7b5c",
    "title": "Mortgage",
    "description": "...",
    "has_draft": false,
    "has_published": true
  },
  "activities": [
    {
      "id": "...",
      "title": "Monthly payment",
      "description": "...",
      "equation": "...",
      "state": "published",
      "variable_refs": [
        { "variable_id": "...", "calculable": true }
      ]
    }
  ],
  "variables": [
    {
      "id": "...",
      "key": "interest_rate",
      "title": "Interest rate",
      "description": "...",
      "default_value": "0",
      "display_type": "percent",
      "display_metadata": {
        "number": { "decimal_format": "decimals_2" }
      }
    }
  ],
  "version": 1
}
```

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

| Field                   | Type    | Description                                                                                                                                   |
| ----------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | UUID    | The domain.                                                                                                                                   |
| `key`                   | string  | The domain's key — an auto-generated, immutable identifier (`dm_` followed by hex). The same domain copied to another account keeps this key. |
| `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](/concepts/activities):

| Field                   | Type   | Description                                                                                   |
| ----------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `id`                    | UUID   | The activity.                                                                                 |
| `title` / `description` | string | Labels.                                                                                       |
| `equation`              | string | The activity's equation.                                                                      |
| `state`                 | string | `published` or `disabled`.                                                                    |
| `variable_refs[]`       | array  | The variables the activity references — each a `variable_id` with whether it is `calculable`. |

**Variables** — one entry per [variable](/concepts/variables), in definition form:

| Field                   | Type   | Description                                                                                                                        |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | UUID   | The variable.                                                                                                                      |
| `key`                   | string | The variable name used in equations.                                                                                               |
| `title` / `description` | string | Labels.                                                                                                                            |
| `default_value`         | string | The value applied when none is provided, as a combined `"value unit"` string, or an empty string when the variable has no default. |
| `display_type`          | string | The variable's type: `number`, `percent`, `no_separator`, `table`, `bar_chart`, or `pie_chart`.                                    |
| `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`:

```json theme={null}
"display_metadata": {
  "number": { "decimal_format": "decimals_2" }
}
```

The inner object carries the same fields as the matching [`display` object](/api/calculate#display-formats) in a calculation result — `decimal_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.

#### Display configuration vs. display

The same variable's formatting appears in two shapes, and `display_type` does not mean the same thing in each:

|              | `/domains/:id/activities` (definition)                                                       | `/calculate` (result)                                                           |
| ------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Structure    | nested under the type key: `display_metadata.<type>.{...}`                                   | flat: `display.{...}`                                                           |
| Type field   | `display_type` is the variable's whole type, including `table`, `bar_chart`, and `pie_chart` | split into `data_type` (structural) and `display_type` (scalar formatting only) |
| Completeness | as stored — optional fields may be absent                                                    | normalized — defaults filled, empty collections shown as `{}`                   |

The overloaded `display_type` is the gotcha: in a definition it can be `table`, but in a result `display_type` is only ever a scalar format and the structural type lives in `data_type`.