--- title: "Preview an atomic rule-configuration change set" method: POST path: "/v1/programs/{program_id}/rule-configuration/preview" tags: ["Rules"] --- # Preview an atomic rule-configuration change set `POST /v1/programs/{program_id}/rule-configuration/preview` ## Request - Base URL: `https://api.scrip.dev` - URL: `https://api.scrip.dev/v1/programs/{program_id}/rule-configuration/preview` - Auth: HTTP bearer Check a complete proposed rule configuration and return its changes, warnings, and the `preview_token` and `request_hash` to apply it. ## Path parameters - `program_id` string, uuid, required ## Request body - PreviewRuleConfigurationRequest (unresolved $ref) ## Response `200` The planned changes, and the token and hash to apply them - PreviewRuleConfigurationResponse: The changes a proposed rule configuration would make, and the token and hash to apply it. - `base_rule_configuration_version` integer: Configuration version the preview was planned from. - `change_id` string, uuid: The id of this change. The apply response and the revision history carry the same id. - `diff` RuleConfigurationDiffResponse: The rule sets and rules that a rule configuration change creates, updates, moves or removes. - `rule_sets` RuleConfigurationResourceDiffResponse[]: Created, updated, moved, or otherwise changed rule sets. - `after` unknown - `before` unknown - `change_type` 'CREATE' | 'UPDATE' | 'MOVE' | 'STATUS' | 'ARCHIVE' | 'REMOVE': How the resource changed. - `client_ref` string: Request-local identity when the resource is created by this change set. - `fields` string[]: Fields whose values changed. - `id` string, uuid: The id of the rule set or rule that changed. - `rules` RuleConfigurationResourceDiffResponse[]: Created, updated, moved, archived, or otherwise changed rules. - `after` unknown - `before` unknown - `change_type` 'CREATE' | 'UPDATE' | 'MOVE' | 'STATUS' | 'ARCHIVE' | 'REMOVE': How the resource changed. - `client_ref` string: Request-local identity when the resource is created by this change set. - `fields` string[]: Fields whose values changed. - `id` string, uuid: The id of the rule set or rule that changed. - `expires_at` string, date-time: When `preview_token` stops working. - `local_references` object: Mapping from each client_ref to its preview-allocated stable UUID. - `preview_token` string: The token to send to apply. Nobody else can use it, and it stops working at `expires_at`. - `proposed_rule_configuration` RuleConfigurationPlan: The rule configuration Scrip will save when you apply a preview. - `base_rule_configuration_version` integer: The rule configuration version this plan was made from. - `program_id` string: The program the plan belongs to. - `rule_sets` PlannedRuleSet[]: The rule sets, with their rules, that will exist after you apply the plan. - `client_ref` string: The `client_ref` you sent for this rule set, when the rule set is new. - `existing` boolean: Whether the rule set already exists. It is false for a rule set that applying the change creates. - `id` string: The id of the rule set. Scrip assigns it when the rule set is new. - `key` string: The key of the rule set, unique in the program. - `name` string: The name people see for the rule set. - `order` integer: The position of the rule set in the program. Lower numbers run first. - `rules` PlannedRule[]: The rules in the rule set, in order. - `actions` RuleAction[]: The actions Scrip takes when the rule matches. - union: A single action to execute when a rule matches. Actions are flat objects: every field sits at the top level alongside `type`, and `type` selects which fields are allowed. Fields that do not appear in the selected branch are rejected. - RuleActionCredit (unresolved $ref) - RuleActionDebit (unresolved $ref) - RuleActionHold: Move value from `AVAILABLE` to `HELD`. Use `reference_id` to link the hold to a later `RELEASE`; this requires a LOT-mode asset. - … - union: Release held funds back to the available bucket. Provide amount for a partial release, or reference_id to release the correlated hold. At least one of the two is required. - … - RuleActionForfeit: Forfeit an amount out of the participant's balance. Requires asset_id and a positive amount. reference_id is not supported. - … - RuleActionVoidPending: Cancel pending rewards credited into `HELD` for `reference_id` and return the value to its source. Requires `reference_id` and a LOT-mode asset. Omit `amount` to cancel all pending rewards, or set a positive amount in asset units to cancel part, newest lots first. An amount above the pending balance cancels only what remains. A blank `amount` is rejected. Do not send `bucket`. - … - RuleActionTag (unresolved $ref) - RuleActionUntag (unresolved $ref) - RuleActionCounter (unresolved $ref) - RuleActionSetAttribute (unresolved $ref) - RuleActionSetTier (unresolved $ref) - RuleActionScheduleEvent (unresolved $ref) - RuleActionBroadcast: Send an event to every participant in the program. Delivery starts without a delay and runs asynchronously. Do not send `target`; the broadcast already reaches everyone. Use `SCHEDULE_EVENT` for a delayed event. - … - `active_from` string, date-time: The earliest event time the rule applies to, as an RFC 3339 timestamp. - `active_to` string, date-time: The event time the rule stops applying, as an RFC 3339 timestamp. - `budgets` BudgetSpec[]: The spending limits on the rule. - union: Limit on how much of one asset this rule can credit. Use PROGRAM for a shared limit or PARTICIPANT for a limit per recipient. One budget is allowed per asset and scope. Omit schedule_type for a lifetime limit, or choose CRON or INTERVAL to reset it on a schedule. - object: Never resets. schedule_type, cron_expression, and interval are all rejected. - … - object: Resets on a UTC cron schedule. For PARTICIPANT budgets, every participant resets at the same time. Requires cron_expression without a timezone. Do not send interval. - … - object: Resets after each interval. For PARTICIPANT budgets, each participant's period starts with their first credit from this rule. Requires interval. Do not send cron_expression. - … - `client_ref` string: The `client_ref` you sent for this rule, when the rule is new. - `condition` string: The CEL condition that decides whether the rule matches an event. - `description` string: What the rule is for. - `existing` boolean: Whether the rule already exists. It is false for a rule that applying the change creates. - `id` string: The id of the rule. Scrip assigns it when the rule is new. - `name` string: The name people see for the rule. - `order` integer: The position in the list. Lower numbers run first. - `restore_archived` boolean: Whether applying the change restores an archived rule with this name. - `rule_set_id` string: The rule set that holds the rule. - `status` 'ACTIVE' | 'SUSPENDED': Whether the rule is ACTIVE or SUSPENDED. - `stop_after_match` boolean: Whether a match stops the rest of the rule set from running. - `request_hash` string: The hash to send to apply with `preview_token`. - `source` RuleConfigurationSourceResponse: Who or what made a rule configuration change, so you can match it to your own records. - `reference` string: Correlation reference the caller supplied with the change, if any. - `source_revision` integer: Historical revision restored when the change was a forward rollback. - `type` 'API' | 'DASHBOARD' | 'MCP' | 'SDK' | 'CONFIG_AS_CODE' | 'SCENARIO_PROMOTION': Which kind of caller made the change. - `warnings` RuleConfigurationPreviewWarning[]: Non-blocking advisories found while validating the proposed configuration. - `client_ref` string: The `client_ref` of the rule, when the rule is new. - `code` string: What the warning is about. On a rule: `unknown_state_key` (a key no rule writes), `deprecated_alias`, or `possible_unmarked_expression` (a literal that looks like CEL without `${{ }}`). On a simulation: `missing_participant_context`. On a configuration preview, also `stop_after_match_has_no_following_rule`, `unconditional_stop_shadows_following_rules`, or `later_rule_set_retained_empty`. - `key` string: The referenced key, as written in the condition. - `kind` string: Kind of reference: `counter`, `tag`, `attribute`, or `alias`. - `message` string: Human-readable explanation (includes the suggestion when one exists). - `rule_id` string: Rule identity is populated for complete-configuration validation. The single-rule authoring surfaces omit these fields. - `rule_set_id` string: The id of the rule set that holds the rule. - `scope` string: Where the referenced state belongs: `participant`, `program`, or `group`. - `suggestion` string: Closest known key, when a near-match exists. Empty otherwise. ## Other responses - `400`: The body or the proposed configuration is malformed (code: validation_error | invalid_json) - `401`: The API key is missing or not valid. See [Authentication](https://docs.scrip.dev/authentication). - `403`: The caller is not allowed to do this. - `404`: Program not found (code: program_not_found) - `409`: base_rule_configuration_version is behind the live version, or the program is archived (code: rule_configuration_version_conflict | program_archived) - `429`: Too many requests. Wait the number of seconds in the `Retry-After` header, then retry. See [Limits and durations](https://docs.scrip.dev/limits#rate-limits). - `500`: Something failed on Scrip's side. Retry the request, and quote `request_id` if it keeps failing. [Errors](https://docs.scrip.dev/errors) lists every code, and the [API introduction](https://docs.scrip.dev/api-reference/introduction) describes the error format. --- [API](https://skmtc.dev/scrip/apis/scrip-api.md) · [All operations](https://skmtc.dev/scrip/apis/scrip-api/llms.txt) · [OpenAPI document](https://skmtc.dev/scrip/apis/scrip-api/revisions/c52d35da8d97?raw)