# Sources and rules

> Push accounting rows to a Layerz model over REST, map them to lines with rules, and read back the sources, the routing and the unmapped keys.

A source is the traceable feed behind imported values; its rules map each row to a line. See [Sources and mapping](/docs/concepts/sources-and-mapping). Over REST, a source is fed by rows you push. Connectors (Pennylane, Qonto, Stripe) are connected in the app, and files are imported through the app or MCP.

| Method and path                              | Does                                                                       |
| -------------------------------------------- | -------------------------------------------------------------------------- |
| `GET /models/:id/sources`                    | Every source of the model, with its kind, branches, sync status and window |
| `POST /models/:id/sources`                   | Create a source fed by pushed rows                                         |
| `POST /models/:id/sources/:sourceId/rows`    | Push rows (up to 5,000 per call)                                           |
| `GET /models/:id/sources/:sourceId/rules`    | The source's mapping rules                                                 |
| `PUT /models/:id/sources/:sourceId/rules`    | Create or update rules (up to 500, all or nothing)                         |
| `DELETE /models/:id/sources/:sourceId/rules` | Delete rules by id: `{ "mapping_ids": [...] }`                             |

## Create a source

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | `string` | yes |  |
| `branch_ids` | `string[]` |  |  |

By default the source feeds the base branch. The response is `201` with the source `id`.

## Write the rules

| Field | Type | Required | Description |
|---|---|---|---|
| `rules` | `object[]` | yes |  |

A rule matches a row's `key` with a case-insensitive pattern (`*` anywhere) and routes it to a line (`target`, a uid or a name; `<line uid>::<element uid>` for an element of a list line). `sign: "negate"` reverses the amount. Rules are keyed by pattern: sending the same pattern again updates the rule.

## Push rows

| Field | Type | Required | Description |
|---|---|---|---|
| `rows` | `object[]` | yes |  |
| `mode` | `"periods" \| "replace"` |  |  |
| `dry_run` | `boolean` |  |  |
| `confirm_replace` | `boolean` |  |  |

- `date` is `YYYY-MM-DD` or `YYYY-MM`; the month is the period.
- `key` is what rules match (an account number, a cost code); `label` defaults to the key; `id` is a stable id from your system.
- `mode: "periods"` (default) replaces the source's rows for the months the batch carries and keeps the others: push only the month you close. `mode: "replace"` treats the batch as the whole ledger.
- `dry_run: true` reports what the push would do without writing.

The response is the projection report: what was written where, and the `unmapped` keys no rule matches. Each push moves the source's window, and with it the model's cutover, to its last month.

## A monthly close, end to end

```http
POST /api/v1/models/:id/sources
{ "name": "Monthly close" }

PUT /api/v1/models/:id/sources/:sourceId/rules
{ "rules": [
  { "pattern": "RET-ACME", "target": "Revenue::Acme" },
  { "pattern": "VNG-*", "target": "Contractor costs", "sign": "negate" }
] }

POST /api/v1/models/:id/sources/:sourceId/rows
{ "rows": [
  { "date": "2026-10-31", "key": "RET-ACME", "label": "Acme retainer", "amount": 12000 },
  { "date": "2026-10-31", "key": "VNG-STUDIO", "amount": 3400 }
] }
```

Next month, push November only: October stays as it was.
