Managing rule configuration

A program’s rule configuration is every rule set and non-archived rule Scrip will evaluate: order, status, actions, and budgets. Scrip stores that snapshot under one number, rule_configuration_version, and increases the number by one on every change. Writing rules covers creating and updating one rule at a time. Use this page when more than one writer can change the same program, or when one change touches several rules or sets. The dashboard and the Scrip MCP server follow the same flow.

Choose an endpoint

What you want	Where to send it
Create or edit one rule	`POST /v1/rules` or `PATCH /v1/rules/{id}`
Create or rename one rule set	`POST /v1/programs/{programId}/rule-sets` or `PATCH /v1/programs/{programId}/rule-sets/{ruleSetId}`
Move one rule or set	`/move`, with the current version
Replace one full order	`/order`, with the current version
Change several rules or sets together	`/rule-configuration/preview`, then `/rule-configuration/apply`
See what the program looked like	`/rule-configuration/revisions`
Restore an earlier configuration	`/rollback/preview`, then standard apply

Create and patch on a single rule or set do not check rule_configuration_version, so two writers can overwrite each other. They still return the new version when the write changes the configuration.

Read the current configuration

curl https://api.scrip.dev/v1/programs/$PROGRAM_ID/rule-configuration \
  -H "Authorization: Bearer $SCRIP_API_KEY"

The response is one snapshot: every rule set in execution order, and every ACTIVE and SUSPENDED rule in each set. Archived rules are omitted.

{
  "program_id": "71000000-0000-4000-8000-000000000001",
  "rule_configuration_version": 12,
  "rule_sets": [
    {
      "rule_set": {
        "id": "71000000-0000-4000-8000-000000000010",
        "program_id": "71000000-0000-4000-8000-000000000001",
        "key": "default",
        "name": "Default",
        "order": 1,
        "created_at": "2026-07-16T10:30:00Z",
        "updated_at": "2026-07-18T14:20:00Z"
      },
      "rules": [
        {
          "id": "71000000-0000-4000-8000-000000000021",
          "rule_set_id": "71000000-0000-4000-8000-000000000010",
          "name": "Base earn",
          "order": 1,
          "status": "ACTIVE",
          "condition": "event.type == 'purchase'",
          "actions": [
            {"type": "CREDIT", "asset_id": "71000000-0000-4000-8000-000000000020", "amount": "${{ event.amount }}"}
          ],
          "budgets": [],
          "stop_after_match": false
        }
      ]
    }
  ]
}

Pass rule_configuration_version from this response on move, reorder, preview, and rollback requests. If another writer changes the program first, those requests return 409 rule_configuration_version_conflict. Read the configuration again and rebuild the request from the new snapshot. See Get the complete rule configuration.

Move or reorder

To place one rule or set, send a position of first, last, before, or after. before and after need reference_id. See Rule sets for execution order. Move one set:

POST /v1/programs/{programId}/rule-sets/{ruleSetId}/move
{
  "position": {"placement": "first"},
  "expected_rule_configuration_version": 12
}

Replace the full set order when you already have the sequence you want. The list must contain every current rule set exactly once:

PUT /v1/programs/{programId}/rule-sets/order
{
  "rule_set_ids": [
    "71000000-0000-4000-8000-000000000011",
    "71000000-0000-4000-8000-000000000010"
  ],
  "expected_rule_configuration_version": 12
}

Reorder the ACTIVE and SUSPENDED rules in one set the same way. Include every non-archived rule in that set exactly once. An empty rule_ids list is valid for an empty set:

PUT /v1/programs/{programId}/rule-sets/{ruleSetId}/rules/order
{
  "rule_ids": [
    "71000000-0000-4000-8000-000000000022",
    "71000000-0000-4000-8000-000000000021"
  ],
  "expected_rule_configuration_version": 13
}

Move a rule inside its set, or into another set, in one request:

POST /v1/rules/{ruleId}/move
{
  "rule_set_id": "71000000-0000-4000-8000-000000000011",
  "position": {
    "placement": "after",
    "reference_id": "71000000-0000-4000-8000-000000000022"
  },
  "expected_rule_configuration_version": 14
}

A cross-set move renumbers the source and destination in the same transaction.

Check a draft

Single-rule validation and simulation evaluate one rule. They do not run the rest of the program, so they cannot prove cross-set order, stop_after_match, or conditions that depend on an earlier rule’s writes. Analyze the draft and run a test before you apply a change that spans several rules. Send {} to analyze the live configuration:

POST /v1/programs/{programId}/rule-configuration/analysis
{}

To analyze a draft, send that draft as proposed_configuration in the same shape as preview. Each finding includes severity, confidence, runtime_semantics, and remediation.

Analysis is conservative and advisory. Treat a likely or advisory finding as a reason to inspect and test the draft.

See Analyze a rule configuration. Then send the same draft as rule_configuration to POST /v1/test-runs. The test run evaluates in a transaction that rolls back. It does not change live rules, balances, budgets, or stored state. Testing covers scenario vs replay, compare_live, and traces. The multi-set example shows a layout where set-local stops and the event-start snapshot matter.

Preview and apply

Use preview and apply when one change updates several rule sets, rules, positions, statuses, actions, or budgets. The preview body is the configuration you want, in execution order:

POST /v1/programs/{programId}/rule-configuration/preview
{
  "base_rule_configuration_version": 14,
  "source": {
    "type": "config_as_code",
    "reference": "rewards-config-v42"
  },
  "rule_sets": [
    {
      "id": "71000000-0000-4000-8000-000000000010",
      "key": "default",
      "name": "Default",
      "rules": [
        {
          "id": "71000000-0000-4000-8000-000000000021",
          "name": "Base earn",
          "condition": "event.type == 'purchase'",
          "actions": [
            {"type": "CREDIT", "asset_id": "71000000-0000-4000-8000-000000000020", "amount": "${{ event.amount }}"}
          ],
          "budgets": [],
          "status": "ACTIVE",
          "stop_after_match": false
        },
        {
          "client_ref": "summer-bonus",
          "name": "Summer bonus",
          "condition": "event.type == 'purchase' && event.region == 'US'",
          "actions": [
            {"type": "CREDIT", "asset_id": "71000000-0000-4000-8000-000000000020", "amount": "${{ event.amount * 0.25 }}"}
          ],
          "budgets": [],
          "status": "SUSPENDED",
          "stop_after_match": false
        }
      ]
    }
  ]
}

In the request	What Scrip does
Existing rule set or rule	Identify it with `id`
New rule set or rule	Omit `id` and send a unique `client_ref`
Existing rule set	Repeat its immutable `key`
Every existing rule set	Include it exactly once. Sets cannot be removed.
Rule you want to keep	Include the full definition: `actions`, `budgets`, `status`, and `stop_after_match`
Existing rule you leave out	Archived when you apply
Array order	Becomes the set order and the rule order inside each set

Preview runs the same CEL, action, target, asset, and budget checks as a single-rule write. It does not change the live configuration or increment the version. The response includes:

Field	Meaning
`proposed_rule_configuration`	The plan the server will commit
`diff`	Set-level and rule-level changes
`warnings`	Issues to review before you apply
`local_references`	Each `client_ref` mapped to the UUID Scrip allocated
`preview_token`, `request_hash`, `expires_at`	What you pass to apply

Read the plan, diff, and warnings. Then apply exactly what preview stored:

POST /v1/programs/{programId}/rule-configuration/apply
{
  "preview_token": "opaque-preview-token",
  "request_hash": "64-character-sha256-hash-from-preview"
}

The apply body cannot change the proposal. Scrip verifies the token, expiry, request hash, configuration version, and referenced dependencies, then commits the plan in one transaction. A successful apply increases rule_configuration_version by one. A preview can be applied once. If it expires, was already applied, or no longer matches current dependencies, create a new preview. See Preview a rule-configuration change set and Apply a rule-configuration change set.

History

Each change that takes effect creates one revision. A revision stores the configuration at that version and the diff from the previous one. List revisions, newest first:

GET /v1/programs/{programId}/rule-configuration/revisions?limit=20

Use pagination.next_cursor for the next page. Get one revision:

GET /v1/programs/{programId}/rule-configuration/revisions/{version}

Find the latest tracked revision at or before a timestamp:

GET /v1/programs/{programId}/rule-configuration/revisions/as-of?at=2026-07-18T14:20:00Z

If the timestamp is before tracked history, the response omits revision and returns a caveats entry. Compare two tracked revisions:

GET /v1/programs/{programId}/rule-configuration/revisions/diff?from_version=10&to_version=14

Omit to_version, or pass to_version=current, to compare a tracked revision with the live configuration.

Program-level history starts at earliest_tracked_version. Requests that reach before it return caveats (history_not_yet_tracked, pre_history_legacy_data).

Roll back

Rollback builds a normal preview that restores a past configuration. History is left in place; the restore is a new revision.

POST /v1/programs/{programId}/rule-configuration/revisions/{version}/rollback/preview
{
  "expected_rule_configuration_version": 18,
  "source": {
    "type": "dashboard",
    "reference": "incident-rollback"
  }
}

Review the plan, inverse diff, and warnings. Apply it with the same preview_token and request_hash as any other preview. Rule sets created after the target revision remain, with no rules, because rule sets cannot be deleted. The preview warns about each of those sets. Rules created after the target are archived. Existing rule and rule-set IDs stay the same. The new revision records source_revision, so you can see which historical configuration was restored and who applied it. See Preview a rule-configuration rollback.

If a request fails

Signal	What to do
`409 rule_configuration_version_conflict`	Read the configuration again. Rebuild the change from that snapshot, then retry.
`422 invalid_position` or invalid membership	Read the containing set. Use `before` or `after`, or send every current member exactly once.
Failed test run	Inspect the rule trace. Fix the draft or the scenario before you preview.
Analysis or preview warning	Read `severity`, `confidence`, `runtime_semantics`, and `remediation`.
`rule_configuration_preview_expired`	Preview the current draft again.
`rule_configuration_dependency_drift`	Re-read the assets, targets, tiers, or other referenced resources, then preview again.
`rule_configuration_preview_already_applied`	Read the current configuration and history before doing more work.
`401` or `403`	Fix credentials. Do not retry the write through another tool.

Getting Started

Foundations

Earning

Participant State

Ledger & Balances

Spending

Operations

Advanced

Reference

Managing rule configuration

Choose an endpoint

Read the current configuration

Move or reorder

Check a draft

Preview and apply

History

Roll back

If a request fails

​Choose an endpoint

​Read the current configuration

​Move or reorder

​Check a draft

​Preview and apply

​History

​Roll back

​If a request fails

Choose an endpoint

Read the current configuration

Move or reorder

Check a draft

Preview and apply

History

Roll back

If a request fails