Browse the documentation

REST API

Items

REST endpoints for the lines, sections and dashboard widgets of a Layerz model, one at a time or in batches of up to 100, with dependents and safe deletion.

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 pathDoes
GET /models/:id/itemsEvery item, in order
POST /models/:id/itemsCreate one item
GET /models/:id/items/:uidOne item
PATCH /models/:id/items/:uidUpdate the fields you send
DELETE /models/:id/items/:uidDelete one item
GET /models/:id/items/:uid/dependentsThe items that reference it
POST /models/:id/items/batchCreate up to 100 items
PATCH /models/:id/items/batch-updateUpdate up to 100 items
POST /models/:id/items/batch-deleteDelete up to 100 items
POST /models/:id/items/reorderReorder tabs, or the children of a container

Create an item

FieldTypeRequiredDescription
role"assumption" | "formula" | "callup" | "balance" | "section" | "chart" | "dashboard" | "kpi" | "mini_table"yes
display_namestringyes
timeline_ref"constant" | "monthly" | "yearly" | "quarterly"
valuenumber | null
values(number | null)[]
formulastring
inputsstring[]
source_uidstring
childrenobject[]
liste_refstring
timeline_valuesobject
is_balanceboolean
opening_balancenumber
item_style"normal" | "subtotal" | "total" | "kpi"
is_subtotalboolean
formatstring
aggregation"sum" | "average" | "stock" | "first"
parent_layer_uidstring
temp_idstring
chart_type"line" | "bar" | "area" | "bridge"
seriesstring[]
bridge_configobject
target_uidstring
target_periodstring
series_defsobject[]
compare_toobject | null
sparklineboolean
table_rowsstring[]
table_row_stylesobject | null
table_axis"time" | "branches" | "list"
table_branchesstring[]
table_liste_refstring
table_varianceobject
spanobject
row_breakboolean
collapsedboolean
positionobject | null
period_windowobject | null
period_mode"period" | "ytd"
checkobject

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) and values (one per period) are exclusive; setting one clears the other.
  • A list line takes timeline_values keyed by element uid or label. On a non-list line, a period-keyed map edits single cells: { "2027-06": [-120] }.
  • inputs is 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.

FieldTypeRequiredDescription
branch_idstringBranch 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_namestring
timeline_ref"constant" | "monthly" | "yearly" | "quarterly"
valuenumber | null
values(number | null)[]
formulastring
inputsstring[]
source_uidstring
childrenobject[]
is_balanceboolean
opening_balancenumber
item_style"normal" | "subtotal" | "total" | "kpi"
is_subtotalboolean
liste_refstring
timeline_valuesobject
formatstring
aggregation"sum" | "average" | "stock" | "first"
parent_layer_uidstring | null
chart_type"line" | "bar" | "area" | "bridge"
seriesstring[]
bridge_configobject
target_uidstring
target_periodstring
series_defsobject[]
compare_toobject | null
sparklineboolean
table_rowsstring[]
table_row_stylesobject | null
table_axis"time" | "branches" | "list"
table_branchesstring[]
table_liste_refstring
table_varianceobject
spanobject
row_breakboolean
collapsedboolean
positionobject | null
period_windowobject | null
period_mode"period" | "ytd"
checkobject | null

Batches

  • Create (POST /models/:id/items/batch): { "items": [...] }. An item may carry a temp_id that later items of the batch use in parent_layer_uid, source_uid, children and 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=:

StrategyEffect on dependents
replace_with_zeroReferences become 0
mark_brokenDependents are flagged broken
delete_dependentsDependents 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.

FieldTypeRequiredDescription
uidsstring[]yes
layer_uidstring