# REST API

> The Layerz REST API under /api/v1, for integrations that create, edit, compute and feed financial models over HTTP. Conventions and every route.

The REST API serves integrations that drive Layerz from code: a script that builds a model, a pipeline that pushes the monthly close, a back office that reads computed figures. AI agents usually prefer the [MCP server](/docs/mcp/overview), which covers more (imports from files, export, branches, history) and carries the modelling context.

## Conventions

- **Base URL**: `https://layerz.cc/api/v1`.
- **Authentication**: `Authorization: Bearer <token>` on every call. See [Authentication](/docs/api/authentication).
- **Format**: JSON in, JSON out, UTF-8. Dates are `YYYY-MM-DD`, periods `YYYY`, `YYYY-Qn` or `YYYY-MM`.
- **References**: items are addressed by their `uid`; most write endpoints also accept an item's name where a uid is expected.
- **Values** are expressed in the model's conventions (currency, units, signs), stated in its [FINANCE.md](/docs/reference/finance-md).
- **Versions**: every write that changes a model records a version.
- **Errors and limits**: see [Limits and errors](/docs/api/limits-and-errors).

## Routes

Generated from the server's route files.

| Path (under `/api/v1`) | Methods |
|---|---|
| `/mapping-sets` | `GET` `POST` |
| `/mapping-sets/:id` | `GET` `DELETE` |
| `/mapping-sets/:id/mappings` | `POST` |
| `/models` | `GET` `POST` |
| `/models/:id` | `GET` `PATCH` `DELETE` |
| `/models/:id/blueprint` | `POST` |
| `/models/:id/compute` | `GET` |
| `/models/:id/duplicate` | `POST` |
| `/models/:id/external-refs` | `GET` `POST` |
| `/models/:id/external-refs/:uid` | `DELETE` |
| `/models/:id/external-refs/refresh` | `POST` |
| `/models/:id/finance-md` | `GET` `PUT` |
| `/models/:id/items` | `GET` `POST` |
| `/models/:id/items/:uid` | `GET` `PATCH` `DELETE` |
| `/models/:id/items/:uid/dependents` | `GET` |
| `/models/:id/items/batch` | `POST` |
| `/models/:id/items/batch-delete` | `POST` |
| `/models/:id/items/batch-update` | `PATCH` |
| `/models/:id/items/reorder` | `POST` |
| `/models/:id/lists` | `GET` `POST` |
| `/models/:id/lists/:listId` | `GET` `PATCH` `DELETE` |
| `/models/:id/snapshot` | `GET` `PUT` |
| `/models/:id/sources` | `GET` `POST` |
| `/models/:id/sources/:sourceId/rows` | `POST` |
| `/models/:id/sources/:sourceId/rules` | `GET` `PUT` `DELETE` |
| `/models/:id/versions` | `GET` `POST` |
| `/models/:id/versions/:versionId` | `GET` `PATCH` `POST` |
| `/models/:id/versions/:versionId/diff` | `GET` |
| `/templates` | `GET` |
| `/templates/:id` | `GET` |

## Pages

- [Models](/docs/api/models): create, read, update, duplicate, blueprint, FINANCE.md.
- [Items](/docs/api/items): lines, sections and widgets, one by one or in batches.
- [Lists](/docs/api/lists): list registries and their elements.
- [Sources and rules](/docs/api/sources-and-rules): push rows and map them to lines.
- [Compute and snapshot](/docs/api/compute-and-snapshot): computed values, the whole model as JSON.
- [Versions](/docs/api/versions), [Templates](/docs/api/templates), [External references](/docs/api/external-refs), [Mapping sets](/docs/api/mapping-sets).
