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.

List domains

GET /v1/domains

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

List a domain’s variables

GET /v1/domains/:id/variables

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

{
  "domain": { "id": "6ba7b810-...", "title": "Mortgage", "description": "..." },
  "variables": [
    {
      "id": "...",
      "key": "home_price",
      "title": "Home price",
      "description": "...",
      "default_value": "0 USD",
      "display_type": "number",
      "decimal_format": "decimals_2"
    }
  ],
  "version": 1
}

Each variable carries exactly these fields: id, key, title, description, default_value, display_type, and decimal_format.

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.
`display_type`	string	`number`, `percent`, `no_separator`, `duration`, `date`, `datetime`, `time`, `table`, `bar_chart`, or `pie_chart`.
`decimal_format`	string \| null	The format applied when the value is shown, from the vocabulary its `display_type` takes. `null` for `table`, `bar_chart`, and `pie_chart`, whose formats live per column or per series — read those from `/activities`.

Rendering a default value

default_value is not self-describing, so pair it with display_type and decimal_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.

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",
      "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.
`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 — 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.
`display_type`	string	The variable’s type: `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.
`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. 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.decimal_format:

"display_metadata": {
  "number": { "decimal_format": "date_med" }
}

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 is 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

Rendering a default value

List a domain’s activities

display_metadata

Display configuration vs. display

​List domains

​List a domain’s variables

​Rendering a default value

​List a domain’s activities

​display_metadata

​Display configuration vs. display

List domains

List a domain’s variables

Rendering a default value

List a domain’s activities

display_metadata

Display configuration vs. display