# Lists

> REST endpoints for the lists of a Layerz model, the registries of departments, products or tranches that list-mode lines expand over.

A list is a named registry of elements that lines expand over. See [Lists](/docs/concepts/lists).

| Method and path                    | Does                                                          |
| ---------------------------------- | ------------------------------------------------------------- |
| `GET /models/:id/lists`            | Every list with its elements                                  |
| `POST /models/:id/lists`           | Create a list (idempotent by name)                            |
| `GET /models/:id/lists/:listId`    | One list                                                      |
| `PATCH /models/:id/lists/:listId`  | Rename it, relabel or remap elements                          |
| `DELETE /models/:id/lists/:listId` | Delete it; bound lines lose their list and per-element values |

## Create

| Field | Type | Required | Description |
|---|---|---|---|
| `display_name` | `string` |  |  |
| `items` | `object[]` |  |  |

```json
{
  "display_name": "Departments",
  "items": [{ "label": "Sales" }, { "label": "Product" }, { "label": "G&A" }]
}
```

A second call with the same name returns the existing list. A list holds at most 500 elements.

## Update

| Field | Type | Required | Description |
|---|---|---|---|
| `display_name` | `string` |  |  |
| `items` | `object[]` |  |  |

`mapped_to` on an element links it to elements of another list, read by subscripts such as ``Repayment[`Banks`]``. Removing an element drops its series on every line bound to the list.
