> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup progress

> Read a context's aggregated setup and activation-readiness state in a single request to drive an onboarding checklist or setup wizard.

The setup-progress endpoint returns configured-resource counts, the last-run state, and activation readiness for a context in a single aggregate — so a setup wizard or onboarding checklist derives its state from one request instead of many.

## Get setup progress

***

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/setup-progress" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "sources": { "total": 2, "left": 1, "right": 1 },
  "fieldMaps": { "mappedSources": 2 },
  "matchRules": { "total": 3 },
  "schedules": { "total": 1 },
  "lastRun": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "completedAt": "2025-01-15T10:30:00Z"
  },
  "readiness": {
    "ready": true,
    "missing": []
  },
  "next": null
}
```

## What it returns

***

* **`status`** — the context lifecycle status: `DRAFT` (being configured), `ACTIVE` (running), `PAUSED` (suspended), or `ARCHIVED` (retired).
* **`sources`** — source counts split by matching side: `total`, `left`, `right`.
* **`fieldMaps.mappedSources`** — number of **mapped** sources: those with a field map, plus CAMT.053 sources, which are self-mapped (the parser embeds the ISO 20022 mapping and ignores field maps).
* **`matchRules.total`** — match-rule count for the context.
* **`schedules.total`** — schedule count for the context.
* **`lastRun`** — the most recent match run (`id`, `status` of `PROCESSING`/`COMPLETED`/`FAILED`, and `completedAt`). It is `null` when the context has never run.
* **`readiness`** — activation-readiness summary (see below).
* **`next`** — the deterministic next setup action to take, or `null` when the context is ready (see below).

## Readiness and the checklist

***

The `readiness` block reports whether the context satisfies every activation requirement:

```json theme={null}
{
  "ready": false,
  "missing": ["field_maps", "match_rules"]
}
```

`missing` holds **stable slugs** you can map to per-requirement checklist items. The possible values are:

* `sources_left` — the context needs at least one LEFT-side source.
* `sources_right` — the context needs at least one RIGHT-side source.
* `field_maps` — at least one source is unmapped: it has no field map and is not a self-mapped CAMT.053 source.
* `match_rules` — the context needs at least one match rule.
* `fee_rules` — the context enables fee normalization but has no fee rule. This requirement is **conditional**: it appears only when `feeNormalization` is set (`NET` or `GROSS`), and it mirrors the run precondition, which gates on fee **rules** — not fee schedules — being non-empty.

<Note>When a context is transitioned to `ACTIVE` before it is ready, the update is rejected with the generic configuration invalid-state `409`. That response does not include the missing slugs. Re-read setup progress after the conflict and use `readiness.missing` to render the remaining setup guidance.</Note>

## The next action

***

`next` turns `readiness.missing` into a concrete call. It is derived from `missing[0]` — the first unsatisfied requirement in the stable order above — and is `null` when the context is ready:

```json theme={null}
{
  "slug": "field_maps",
  "action": "add_field_map",
  "operationId": "createFieldMap",
  "method": "POST",
  "path": "/v1/contexts/{contextId}/sources/{sourceId}/field-maps",
  "requiredFields": ["mapping"],
  "forSource": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Bank statement"
  }
}
```

* **`slug`** — the readiness slug this action satisfies.
* **`action`** — a stable semantic label you can key UI copy on.
* **`operationId`**, **`method`**, **`path`** — the endpoint to call to satisfy the requirement.
* **`requiredFields`** — the **names** of the fields that create request requires. They never carry values; you supply those.
* **`forSource`** — present only for the `field_maps` action, naming the first unmapped source so you can fill `{sourceId}` without a separate lookup.

The full slug-to-action table:

| `slug`          | `action`           | Endpoint                                                      | `requiredFields`                |
| --------------- | ------------------ | ------------------------------------------------------------- | ------------------------------- |
| `sources_left`  | `add_left_source`  | `POST /v1/contexts/{contextId}/sources`                       | `name`, `type`, `side`          |
| `sources_right` | `add_right_source` | `POST /v1/contexts/{contextId}/sources`                       | `name`, `type`, `side`          |
| `field_maps`    | `add_field_map`    | `POST /v1/contexts/{contextId}/sources/{sourceId}/field-maps` | `mapping`                       |
| `match_rules`   | `add_match_rule`   | `POST /v1/contexts/{contextId}/rules`                         | `priority`, `type`, `config`    |
| `fee_rules`     | `add_fee_rule`     | `POST /v1/contexts/{contextId}/fee-rules`                     | `side`, `feeScheduleId`, `name` |

Both source-side actions resolve to the same `createSource` operation — the `side` field is what distinguishes them.

## How to use it during setup

***

1. **Render the checklist.** On each step of the wizard, GET setup-progress and use the counts (`sources`, `fieldMaps`, `matchRules`, `schedules`) to tick off completed items.
2. **Drive the primary button from `next`.** Instead of reimplementing the requirement order client-side, call the operation `next` names; re-read setup-progress afterwards to get the following action.
3. **Gate the "Activate" button.** Enable activation only when `readiness.ready` is `true`; otherwise list `readiness.missing` as the remaining steps.
4. **Show run health.** Once `lastRun` is present, surface its `status` and `completedAt` so operators can confirm the context is producing results.

Because the whole state comes from one call, you can poll this endpoint to keep the wizard live without orchestrating separate source, rule, and run reads.

## Response codes

***

| Status | Meaning                 |
| ------ | ----------------------- |
| `200`  | Setup progress returned |
| `404`  | Context not found       |