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

# Risk Segmentation Configs

**Risk segmentation configurations** are saved views for the Risk Segmentation dashboard on an analysis. Each config
describes how results should be broken down (the **segments**), which summary **columns** appear in the table, and
optional dashboard **filters**. Configs correspond to the segment picker in the web application.

This API manages those saved configurations only. It does **not** return dashboard table data or support drilling into
entries. (The web app loads table rows through separate private endpoints.)

Each config belongs to one analysis. `analysisId` is the analysis **run** id (the same id returned by `/v1/analyses` for
the run, not the analysis context id). Names must be unique within an analysis.

### Typical workflow

1. **Create** a config with `analysisId`, a unique `name`, ordered `segments`, and ordered `columns`.
2. **Query** configs for an analysis (for example `{ "$eq": ["analysisId", "<analysis-run-id>"] }`).
3. **Read** a config by id when you need the full definition.
4. **Delete** configs you no longer need.

There is no update operation on the public API. To change a config, delete it and create a new one.

### Segments

`segments` is an ordered list. Order defines the hierarchy shown in the dashboard table (outer segments first, inner
segments nested beneath them). Each value must be a valid SQL identifier.

**`risk_score` is required** in `segments`. Create requests without it are rejected.

#### Built-in segment keys (general ledger and similar analyses)

| Segment | Meaning |
| - | - |
| `risk_group` | Risk assertion category (for example asset vs profit-and-loss assertion scores). |
| `risk_score` | Individual risk score (ensemble). **Required.** |
| `account_l1` … `account_l5` | Account grouping hierarchy levels. Use only levels that exist for the analysis. |
| `population_<code>` | Group by a population tag code (prefix is literal `population_`). |
| `category_<code>` | Group by a population category code (prefix is literal `category_`). |

The web application builds population segment ids from enabled populations on the analysis.

#### Custom analysis segments

For custom (flex) analyses, additional segment fields may be used when they name **categorical** columns on the
analysis entry data table. Those names must be valid SQL identifiers and must exist on the table. The analysis
designer uses the same rules when defining risk segmentation there.

### Columns

`columns` is an ordered list of metric fields displayed in the dashboard table for each segment row. Values must match
the snake\_case ids below (these are the same ids the web application sends as `columns`).

#### Count and value summaries

| Column | Meaning |
| - | - |
| `total_count` | Entry count in the segment. |
| `total_value` | Total monetary value. |
| `total_value_dr` | Total debit value. |
| `total_value_cr` | Total credit value. |
| `net_activity` | Net activity value. |
| `risk_avg` | Average risk score in the segment. |

#### High / medium / low counts and values

| Column | Meaning |
| - | - |
| `high_count`, `medium_count`, `low_count` | Entry counts at each risk level. |
| `high_value`, `medium_value`, `low_value` | Monetary totals at each risk level. |
| `high_value_dr`, `high_value_cr`, … | Debit/credit splits of H/M/L value columns (same pattern as above). |

#### High / medium / low percentages

| Column | Meaning |
| - | - |
| `percent_high_risk`, `percent_med_risk`, `percent_low_risk` | Percent of entries at each risk level. |
| `percent_high_risk_dr`, `percent_high_risk_cr`, … | Debit/credit splits of the percentage columns (same pattern). |

Debit/credit column variants apply to general ledger analyses that expose separate debit and credit totals. Omit them
when not relevant to the analysis type.

Do **not** put segment keys (such as `risk_group` or `account_l1`) in `columns`; those belong in `segments`.

### Optional filters

These fields mirror the **Risk group** and **Risk score** filters on the dashboard facet bar. They restrict which
scores and categories are in scope when the config is opened. They do not add extra grouping levels.

| Field | Meaning |
| - | - |
| `riskScoreIds` | Risk score ids (ensemble object ids) to include. When omitted or empty, all enabled risk scores for the analysis are in scope. When `risk_score` is not a segment, this still limits which scores contribute to aggregated columns. |
| `riskGroups` | Risk group category names to include (for example `GENERAL`, `ASSETS`, `PROFIT_LOSS`, or a custom risk score category name). When omitted or empty, all groups are in scope. |

`riskGroups` values are **category labels**, not risk range ids and not entries from `/v1/risk-ranges`.

### Other fields

| Field | Meaning |
| - | - |
| `displayCellVisuals` | When `true`, the dashboard shows in-cell sparkline visuals for numeric columns. Defaults to `false`. Maps to internal `displayTableSparklines`. |
| `enabled` | Whether the config is active. Defaults to `true`. Disabled configs remain stored but are not selected by default in the web application. |
| `analysisTypeId` | Set automatically on create from the analysis. Returned on read and query; do not send on create. |

### Example create request

```json theme={null}
{
  "analysisId": "123456789012345678901234",
  "name": "Risk group and score",
  "segments": ["risk_group", "risk_score"],
  "columns": ["total_count", "total_value", "risk_avg"],
  "displayCellVisuals": false,
  "enabled": true,
  "riskScoreIds": ["abcdefabcdefabcdefabcd"],
  "riskGroups": ["GENERAL", "PROFIT_LOSS"]
}
```

### Validation

* `analysisId` must reference an existing analysis run.
* `name` must be unique among configs for that analysis.
* `segments` must include `risk_score`.
* Segment and column names must be valid SQL identifiers.
* Invalid segment or column combinations for the analysis type may be rejected at create time.

### Query

See the query operation description for filterable fields.