Domains

These endpoints let you discover the domains available to your account and inspect their variables and activities. Only published domains are returned.

List domains

GET /v1/domains

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

List a domain’s variables

GET /v1/domains/:id/variables

Returns the domain and its variables, each with a default value and data type. Useful for building structured text.

{
  "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), 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

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-...",
    "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:

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, 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:

"display_metadata": {
  "number": { "decimal_format": "decimals_2" }
}

The inner object carries the same fields as the matching display object 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.

Introduction

Quickstart

Concepts

Domain Library

Playground

Authoring Domains

Data Types

Units

Function Library

API Reference

Resources

List domains

List a domain’s variables

List a domain’s activities

display_metadata

Display configuration vs. display

​List domains

​List a domain’s variables

​List a domain’s activities

​display_metadata

​Display configuration vs. display

List domains

List a domain’s variables

List a domain’s activities

display_metadata

Display configuration vs. display