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

# Rules

> Guide the fraud engine with workspace rules, and set score cut lines for action.

Rules are workspace guidance the engine evaluates on every document. When a rule triggers, its
`score_delta` moves `risk_score`, and the fired rule appears on the check under `rules`.

Reading rules needs `view_documents`; creating, editing, and deleting them needs
`manage_documents`. See [Permissions](/authentication#permissions).

## List rules

```bash theme={null}
curl https://api.sphinxhq.com/api/v1/rules/ \
  -H "Authorization: Bearer $SPHINX_API_KEY"
```

## Create a rule

```bash theme={null}
curl https://api.sphinxhq.com/api/v1/rules/ \
  -H "Authorization: Bearer $SPHINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Employer must match the application",
    "condition": "The employer on the payslip differs from the one on the application",
    "guidance": "Small spelling differences are fine; a different company is not",
    "outcome_guidance": "REJECTED",
    "score_delta": 25,
    "document_types": ["Payslip"]
  }'
```

| Field              | Required | Notes                                             |
| ------------------ | -------- | ------------------------------------------------- |
| `title`            | yes      | Short name                                        |
| `condition`        | yes      | When the rule applies                             |
| `guidance`         | no       | How the engine should reason                      |
| `outcome_guidance` | no       | `ACCEPTED`, `REJECTED`, or `ADVISORY` (default)   |
| `score_delta`      | no       | -100 to 100. Added to `risk_score` when triggered |
| `document_types`   | no       | Limit to these types; omit to apply to all        |
| `status`           | no       | `active` (default) or `disabled`                  |

## Update / disable / delete

* `PATCH /api/v1/rules/{id}/` with any subset of fields (including `status: "disabled"`)
* `PUT /api/v1/rules/{id}/` replaces the full rule. Omitted optional fields reset to their
  defaults, so use `PATCH` unless you are sending the whole object
* `DELETE /api/v1/rules/{id}/` soft-deletes the rule

Edits apply to documents analysed after the change. Checks already completed keep the rules and
scores they were given.

## Triggered rules on a check

Completed checks include a `rules` array of rules that fired:

```json theme={null}
{
  "rules": [
    {
      "id": "rule_01jq8x...",
      "title": "Employer must match the application",
      "outcome_guidance": "REJECTED",
      "score_delta": 25,
      "reasoning": "The payslip lists Acme Ltd; the application lists Beta Inc."
    }
  ]
}
```

## Thresholds

Map `risk_score` to the check's `action` field (`approve` / `review` / `reject`):

```bash theme={null}
curl https://api.sphinxhq.com/api/v1/thresholds/ \
  -H "Authorization: Bearer $SPHINX_API_KEY"

curl https://api.sphinxhq.com/api/v1/thresholds/ \
  -X PATCH \
  -H "Authorization: Bearer $SPHINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pass_below": 40, "review_below": 80}'
```

Score below `pass_below` → `approve`. Below `review_below` → `review`. Otherwise → `reject`.
Changes apply to new analyses only; each check snapshots the cut lines it used.

## Flag settings

Ignore specific flag codes for this workspace. Ignored flags are omitted from new checks and do
not contribute to `risk_score`. Existing checks are unchanged.

```bash theme={null}
curl https://api.sphinxhq.com/api/v1/flag-settings/ \
  -H "Authorization: Bearer $SPHINX_API_KEY"
```

```bash theme={null}
curl -X PATCH https://api.sphinxhq.com/api/v1/flag-settings/ \
  -H "Authorization: Bearer $SPHINX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"disabled_flag_codes": ["font_inconsistency", "scrubbed_metadata"]}'
```

| Field                 | Notes                                                                       |
| --------------------- | --------------------------------------------------------------------------- |
| `disabled_flag_codes` | Full replace. Empty list re-enables every flag. Unknown codes are rejected. |