# 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](/docs/concepts/items-and-roles) and [Model format](/docs/reference/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:

```json
{ "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.

| 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 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=`:

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