# Contract — <Domain> (backend phase bN)

> One-line: what this domain's API covers. Assumes
> [`../conventions/api-conventions.md`](../conventions/api-conventions.md) +
> [`../conventions/money-and-types.md`](../conventions/money-and-types.md). Source of truth for the
> machine schema: [`../openapi/`](../openapi/README.md).

**Status:** live as of backend-phase-bN · **Frontend consumer:** frontend-phase-fM

## Enums used
- `<enum_name>`: `value_a` | `value_b` | … — meaning of each.

## Endpoints

### `<HTTP> api/v1/<controller>/<action>`
- **Purpose:** …
- **Auth:** none | authenticated | policy/role … · **Rate-limited:** yes/no · **Idempotency key:** yes/no
- **Path/query params:** `name` (type) — meaning; pagination `page`/`page_size` (default/max) for lists.
- **Request body:**
  ```json
  { "field": "example" }
  ```
- **Success `200` payload (`data`):**
  ```json
  { "field": "example" }
  ```
- **Failure cases:** `400` …, `401` …, `403` …, `404` …, `409` … (when/why each).
- **Notes:** masking, two-stage disclosure, tenancy, side effects (notifications/ledger/audit), etc.

_(repeat per endpoint)_

## Shared shapes
- `<DtoName>`: field-by-field (name, type, nullable, masked?, meaning).

## Changelog
- bN — initial contract.