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=replacerebuilds the model, keeping only what a blueprint cannot express (style colours, custom formats, glyph, subtitle, FINANCE.md).dry_run=truevalidates 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.
FINANCE.md
GET /models/:id/finance-md: the model's FINANCE.md (204when it has none).PUT /models/:id/finance-md:{ "content": "<markdown>", "source"?: "auto" | "user" | "imported" }, the whole document, validated.