# Models

> REST endpoints to list, create, read, update, duplicate and delete Layerz models, build them from a blueprint, and read or write their FINANCE.md.

## List models

`GET /models`: the models you can read, each with its `access`, `can_write`, `has_finance_md`, its `url` in the app and its sharing state.

| Query           | Meaning                                                     |
| --------------- | ----------------------------------------------------------- |
| `q`             | Name search, case and accent insensitive; `*` is a wildcard |
| `writable=true` | Only the models you can edit                                |

## Create a model

`POST /models`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` |  | Model name. Required without `file_id`; an imported workbook names the model after its file. |
| `subtitle` | `string` |  |  |
| `glyph` | `string` |  | Emblem icon: a kebab-case Lucide icon name (https://lucide.dev/icons), e.g. "trending-up", "coffee", "landmark". Shown in-app and on the social/OG card. Emojis/free text are rejected with suggestions. Aliases: cash/money→banknote, bank→landmark, cart→shopping-cart, chart/graph→chart-line. |
| `template_id` | `string` |  |  |
| `file_id` | `string` |  | An uploaded workbook (`layerz_create_upload_url`) the model is imported from by the deterministic compiler: live formulas, values where a formula has no equivalent, and the import report (`import`: fidelity, residue, recalculation coverage, constructions map). Exclusive with `template_id`. |
| `anchors` | `object[]` |  | With `file_id`: the first period (`2026`, `2026-01`, `2026-Q1`) of each sheet whose period headers carry no date, as listed by an `IMPORT_DECISION_REQUIRED` error; `[]` leaves those sheets out. |
| `workspace_id` | `string` |  | Workspace the model is created in (one the caller belongs to; `layerz_list_models` lists them). Default: the personal workspace. |
| `timelines` | `object` |  |  |

A new model is empty unless it starts from a template (`template_id`): it has the timelines you send and no section. With `file_id` (a workbook uploaded through MCP), the model is imported instead: the response comes at once with `status: "importing"`, and the import report lands in the model's FINANCE.md.

## Read, update, delete

- `GET /models/:id`: the model in detail, with its items, timelines and lists.
- `PATCH /models/:id`: name, description, subtitle, timelines, glyph.
- `DELETE /models/:id`: owner only.

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` |  |  |
| `subtitle` | `string \| null` |  |  |
| `timelines` | `object` |  |  |
| `glyph` | `string \| null` |  | Emblem icon: a kebab-case Lucide icon name (https://lucide.dev/icons), e.g. "trending-up", "coffee", "landmark". `null` clears it (monogram fallback). Emojis/free text are rejected with suggestions; aliases (cash→banknote, bank→landmark, cart→shopping-cart, chart/graph→chart-line) are normalized. |

Timelines share one horizon snapped to whole months; when a grain is resized, the others realign to it.

## Duplicate

`POST /models/:id/duplicate`

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` |  |  |

## Blueprint

`POST /models/:id/blueprint?mode=merge|replace&dry_run=true` compiles a blueprint (whole sections with their items, referenced by name) into the model in one call.

- `mode=merge` (default) adds to the model and reuses items by name, keeping the presentation a re-declared item omits.
- `mode=replace` rebuilds the model, keeping only what a blueprint cannot express (style colours, custom formats, glyph, subtitle, FINANCE.md).
- `dry_run=true` validates and returns every error with its path, without writing.

The response maps every name to its uid (`name_to_uid`). The blueprint grammar is the one of the MCP tool `layerz_build_from_blueprint`, documented in the [tool reference](/docs/mcp/tools#layerz_build_from_blueprint).

## FINANCE.md

- `GET /models/:id/finance-md`: the model's [FINANCE.md](/docs/reference/finance-md) (`204` when it has none).
- `PUT /models/:id/finance-md`: `{ "content": "<markdown>", "source"?: "auto" | "user" | "imported" }`, the whole document, validated.
