An item is any line, section, dashboard or widget of a model; its role decides which fields apply. See Items and roles and Model format.
Endpoints
| Method and path | Does |
|---|---|
GET /models/:id/items | Every item, in order |
POST /models/:id/items | Create one item |
GET /models/:id/items/:uid | One item |
PATCH /models/:id/items/:uid | Update the fields you send |
DELETE /models/:id/items/:uid | Delete one item |
GET /models/:id/items/:uid/dependents | The items that reference it |
POST /models/:id/items/batch | Create up to 100 items |
PATCH /models/:id/items/batch-update | Update up to 100 items |
POST /models/:id/items/batch-delete | Delete up to 100 items |
POST /models/:id/items/reorder | Reorder tabs, or the children of a container |
Create an item
| Field | Type | Required | Description |
|---|---|---|---|
role | "assumption" | "formula" | "callup" | "balance" | "section" | "chart" | "dashboard" | "kpi" | "mini_table" | yes | |
display_name | string | yes | |
timeline_ref | "constant" | "monthly" | "yearly" | "quarterly" | ||
value | number | null | ||
values | (number | null)[] | ||
formula | string | ||
inputs | string[] | ||
source_uid | string | ||
children | object[] | ||
liste_ref | string | ||
timeline_values | object | ||
is_balance | boolean | ||
opening_balance | number | ||
item_style | "normal" | "subtotal" | "total" | "kpi" | ||
is_subtotal | boolean | ||
format | string | ||
aggregation | "sum" | "average" | "stock" | "first" | ||
parent_layer_uid | string | ||
temp_id | string | ||
chart_type | "line" | "bar" | "area" | "bridge" | ||
series | string[] | ||
bridge_config | object | ||
target_uid | string | ||
target_period | string | ||
series_defs | object[] | ||
compare_to | object | null | ||
sparkline | boolean | ||
table_rows | string[] | ||
table_row_styles | object | null | ||
table_axis | "time" | "branches" | "list" | ||
table_branches | string[] | ||
table_liste_ref | string | ||
table_variance | object | ||
span | object | ||
row_break | boolean | ||
collapsed | boolean | ||
position | object | null | ||
period_window | object | null | ||
period_mode | "period" | "ytd" | ||
check | object |
Required: role and display_name. Attach to a container with parent_layer_uid (a section, a balance, a dashboard or a total). Examples:
{ "role": "assumption", "display_name": "Price", "value": 900 }
{ "role": "assumption", "display_name": "Revenue plan", "timeline_ref": "yearly", "values": [100, 120, 140] }
{ "role": "formula", "display_name": "Interest", "formula": "Debt_M-1 * Rate / 12" }
{ "role": "formula", "display_name": "Total revenue", "children": [{ "uid": "<uid>" }, { "uid": "<uid>" }] }
{ "role": "balance", "display_name": "Cash", "opening_balance": 1200000, "children": [{ "uid": "<flow uid>" }] }
{ "role": "assumption", "display_name": "Salary", "liste_ref": "<list uid>", "timeline_values": { "Sales": [5000], "Product": [6000] } }
{ "role": "kpi", "display_name": "ARR", "parent_layer_uid": "<dashboard uid>", "target_uid": "<uid>", "target_period": "2027" }
value(a constant) andvalues(one per period) are exclusive; setting one clears the other.- A list line takes
timeline_valueskeyed by element uid or label. On a non-list line, a period-keyed map edits single cells:{ "2027-06": [-120] }. inputsis derived from the formula: do not send it.
Update an item
PATCH /models/:id/items/:uid changes only the fields it carries; styles, formats and notes set in the app survive. parent_layer_uid moves the item (null to the root). branch_id writes values on a scenario instead of the base.
| Field | Type | Required | Description |
|---|---|---|---|
branch_id | string | Branch that receives the value write as an overlay of the cells differing from the base (absent or default: the base plan). Structural fields apply model-wide. | |
role | "assumption" | "formula" | "callup" | "balance" | "section" | "chart" | "dashboard" | "kpi" | "mini_table" | ||
display_name | string | ||
timeline_ref | "constant" | "monthly" | "yearly" | "quarterly" | ||
value | number | null | ||
values | (number | null)[] | ||
formula | string | ||
inputs | string[] | ||
source_uid | string | ||
children | object[] | ||
is_balance | boolean | ||
opening_balance | number | ||
item_style | "normal" | "subtotal" | "total" | "kpi" | ||
is_subtotal | boolean | ||
liste_ref | string | ||
timeline_values | object | ||
format | string | ||
aggregation | "sum" | "average" | "stock" | "first" | ||
parent_layer_uid | string | null | ||
chart_type | "line" | "bar" | "area" | "bridge" | ||
series | string[] | ||
bridge_config | object | ||
target_uid | string | ||
target_period | string | ||
series_defs | object[] | ||
compare_to | object | null | ||
sparkline | boolean | ||
table_rows | string[] | ||
table_row_styles | object | null | ||
table_axis | "time" | "branches" | "list" | ||
table_branches | string[] | ||
table_liste_ref | string | ||
table_variance | object | ||
span | object | ||
row_break | boolean | ||
collapsed | boolean | ||
position | object | null | ||
period_window | object | null | ||
period_mode | "period" | "ytd" | ||
check | object | null |
Batches
- Create (
POST /models/:id/items/batch):{ "items": [...] }. An item may carry atemp_idthat later items of the batch use inparent_layer_uid,source_uid,childrenand formulas. - Update (
PATCH /models/:id/items/batch-update):{ "updates": [{ "uid": "<uid or name>", "patch": { ... } }], "dry_run"?: true }. - Delete (
POST /models/:id/items/batch-delete):{ "uids": [...] }.
Batches apply item by item: the response is { succeeded, failed, status, count }, with status 201 or 200 when all applied, 207 when some did, 422 when none did.
Delete safely
Deleting an item that formulas or callups read returns 409 with DEPENDENCY_BLOCK. Read GET /models/:id/items/:uid/dependents first, or pass ?strategy=:
| Strategy | Effect on dependents |
|---|---|
replace_with_zero | References become 0 |
mark_broken | Dependents are flagged broken |
delete_dependents | Dependents are deleted too |
Reorder
POST /models/:id/items/reorder: { "uids": [...] } orders root tabs (dashboards and sections, each in its group). Add "layer_uid": "<container>" to order that container's children.
| Field | Type | Required | Description |
|---|---|---|---|
uids | string[] | yes | |
layer_uid | string |