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

# Rulesets

> Versioned collections of rules.

A **ruleset** is a versioned collection of rules bound to a **context**. Each decision request selects a context, and Specter evaluates it against the one ruleset that is `ACTIVE` for that context.

## Lifecycle

```mermaid theme={null}
flowchart LR
    D[DRAFT] -->|activate| A[ACTIVE]
    A -->|superseded by new activation| I[INACTIVE]
    I -->|rollback| A
```

| Status     | Meaning                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `DRAFT`    | Editable working copy. Created with `POST /api/admin/rulesets`. Only drafts can be edited.         |
| `ACTIVE`   | The live ruleset used for decisions in its context. Exactly **one** ruleset per context is active. |
| `INACTIVE` | A previously active ruleset that was superseded. Can be reactivated by rollback.                   |

* **Activate** (`POST /api/admin/rulesets/{id}/activate`) transitions a `DRAFT` to `ACTIVE` and automatically
  moves the previous active ruleset for that context to `INACTIVE`.
* **Rollback** (`POST /api/admin/rulesets/{id}/rollback`) reactivates an `INACTIVE` ruleset, reverting to a
  known-good configuration.

<Note>
  The single-active-per-context guarantee is enforced, so two rulesets can
  never be active for the same context simultaneously.
</Note>

## Contexts

Contexts let you run different rule strategies for different flows — for example `checkout`, `subscription`, or
`default`. The decision request's `context` field selects which active ruleset applies. If a request names a
context that has no active ruleset, Specter falls back to the active ruleset for the `default` context. If
neither exists, no rules are evaluated and the decision is `ALLOW`.

## Editing

Because only `DRAFT` rulesets are editable, the safe change workflow is:

<Steps>
  <Step title="Create a draft">
    `POST /api/admin/rulesets` (scope `admin:rulesets:create`) with your rules.
  </Step>

  <Step title="Refine">
    `PATCH /api/admin/rulesets/{id}` (scope `admin:rulesets:write`) to adjust
    the draft.
  </Step>

  <Step title="Activate">
    `POST /api/admin/rulesets/{id}/activate` to make it live. The previous
    active ruleset becomes inactive.
  </Step>

  <Step title="Roll back if needed">
    `POST /api/admin/rulesets/{id}/rollback` to reactivate the previous ruleset.
  </Step>
</Steps>

## Related

<Card title="Rule engine" icon="sliders" href="/products/specter/concepts/rule-engine">
  The rule types and evaluation model inside a ruleset.
</Card>