> ## Documentation Index > Fetch the complete documentation index at: https://docs.scrip.dev/llms.txt > Use this file to discover all available pages before exploring further. # Simulate a draft rule > Dry-run a draft rule (not yet saved) against sample event data. The draft is validated exactly like rule create, then evaluated; nothing is persisted and no ledger changes occur. Dry-runs a rule that has not been saved yet. Send `program_id`, a `rule` object (`name`, `condition`, `actions`), and the same `event` and participant-context fields as [Simulate a rule](/api-reference/rules/simulate-a-rule). Nothing persists: no rule is created, no balances change, and no events are recorded. This is the test step of the authoring loop: [validate](/api-reference/rules/validate-a-cel-condition) the condition, simulate the draft here until the behavior looks right, then [create the rule](/api-reference/rules/create-a-rule). The response shape, participant-context rules, and warnings match the saved-rule simulation endpoint, and the response also includes any validation warnings for the draft's expressions. ## OpenAPI ````yaml POST /v1/rules/simulate openapi: 3.0.3 info: contact: email: support@scrip.dev name: Scrip Support url: https://scrip.dev/support description: >- Universal Incentive Infrastructure API for managing loyalty programs, rewards, and participant balances. Scrip provides a complete backend for building incentive and loyalty programs. Core concepts: - **Programs**: Containers for incentive logic (e.g., "Q1 Sales Bonus", "Customer Loyalty") - **Assets**: The currency or points being tracked (e.g., "Bonus Points", "Cash Rewards") - **Participants**: Users who earn and spend assets (identified by external_id) - **Groups**: Collections of participants for team-based incentives - **Rules**: Automated reward logic triggered by events - **Events**: Actions that trigger rule evaluation (e.g., "purchase", "referral") Response formats: - **Collection endpoints** return: {"data": [...], "pagination": {"has_more": true, "next_cursor": "..."}} - **Single-resource endpoints** return the resource directly - **Errors** return: {"code": "...", "message": "...", "details": {...}} — `details` is an optional object, present on input errors only license: name: Proprietary url: https://scrip.dev/license termsOfService: https://scrip.dev/terms title: Scrip API version: '1.0' servers: - url: https://api.scrip.dev security: [] tags: - description: >- Manage incentive programs. Programs are the top-level container for all incentive logic. name: Programs - description: >- Manage asset types (currencies, points). Assets define what participants can earn and spend. name: Assets - description: >- Manage participants and their balances. Participants are identified by external_id from your system. name: Participants - description: Manage participant groups for team-based incentives. name: Groups - description: >- Manage automated reward rules. Rules define conditions and actions triggered by events. name: Rules - description: Ingest events that trigger rule evaluation and reward distribution. name: Events - description: Transfer assets between participants. name: Transfers - description: Access ledger summaries and program activity reports. name: Reporting - description: >- Redeem participant balances for rewards. Supports raw amount redemptions and catalog item redemptions. name: Redemptions - description: >- Manage the reward catalog. Create and manage redeemable items with inventory tracking. name: Rewards - description: >- Schedule and manage automated event dispatching. Automations generate events on cron schedules, at specific times, or by evaluating participant state. name: Automations - description: >- Manage tier types and levels within programs. Tiers define status hierarchies that participants progress through based on qualification rules. name: Tiers - description: Inspect double-entry ledger records for auditing and reconciliation. name: Journal Entries - description: >- Manage webhook endpoints and delivery logs. Webhooks notify your application of real-time events via HTTP POST with HMAC-SHA256 signatures. name: Webhooks paths: /v1/rules/simulate: post: tags: - Rules summary: Simulate a draft rule description: >- Dry-run a draft rule (not yet saved) against sample event data. The draft is validated exactly like rule create, then evaluated; nothing is persisted and no ledger changes occur. operationId: simulateDraftRule requestBody: content: application/json: schema: $ref: '#/components/schemas/handlers.SimulateDraftRuleRequest' description: >- Program context, draft rule, sample event, and optional participant state required: true x-originalParamName: request responses: '200': content: application/json: schema: $ref: '#/components/schemas/handlers.SimulateRuleResponse' description: Simulation result '400': content: application/json: schema: $ref: '#/components/schemas/handlers.ErrBadRequestResponse' description: >- Invalid request, malformed CEL, or invalid action (code: validation_error | bad_request) '401': content: application/json: schema: $ref: '#/components/schemas/handlers.ErrUnauthorizedResponse' description: 'Missing or invalid credentials (code: unauthorized)' '403': content: application/json: schema: $ref: '#/components/schemas/handlers.ErrForbiddenResponse' description: 'Insufficient permissions (code: forbidden)' '404': content: application/json: schema: $ref: '#/components/schemas/handlers.ErrNotFoundResponse' description: 'Program or participant not found (code: not_found)' '415': content: application/json: schema: $ref: '#/components/schemas/handlers.ErrUnsupportedMediaTypeResponse' description: 'Content-Type must be application/json (code: unsupported_media_type)' '500': content: application/json: schema: $ref: '#/components/schemas/handlers.ErrInternalResponse' description: 'Internal server error (code: internal_error)' security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: handlers.SimulateDraftRuleRequest: additionalProperties: false properties: event: description: >- Event is the sample event data to evaluate against the draft rule. Kept as raw JSON so numeric values can be precision-checked before the float64 decode (numbers above ±2^53 are rejected — SCR-323). type: object participant_id: description: >- ParticipantID optionally identifies a real participant whose current state (tags, counters, attributes, tiers) is loaded as the simulation's participant context. Mutually exclusive with participant_state. example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string participant_state: additionalProperties: {} description: >- ParticipantState is optional simulated participant state (tags, counters, attributes), matching the semantics of POST /v1/rules/{id}/simulate. Mutually exclusive with participant_id. type: object program_id: description: >- Program providing the validation and evaluation context (asset linkage, tier keys, participant state lookups) example: 550e8400-e29b-41d4-a716-446655440001 format: uuid type: string rule: allOf: - $ref: '#/components/schemas/handlers.SimulateDraftRule' description: >- Rule is the draft rule to evaluate. It is validated exactly like rule create (CEL syntax, action structure, asset existence and program linkage, tier references) but never persisted. required: - event - program_id - rule type: object handlers.SimulateRuleResponse: properties: evaluation: allOf: - $ref: '#/components/schemas/handlers.SimulateEvaluation' description: Evaluation contains the simulation results rule: allOf: - $ref: '#/components/schemas/handlers.SimulateRuleInfo' description: Rule contains metadata about the rule that was simulated warnings: description: >- Non-blocking advisories about the simulation context — e.g. missing_participant_context when the rule's condition reads participant state but the request supplied neither participant_id nor participant_state, so the condition evaluated against empty defaults. items: $ref: '#/components/schemas/models.RuleWarning' type: array type: object handlers.ErrBadRequestResponse: additionalProperties: false properties: code: description: Code is the machine-readable error code example: bad_request type: string details: allOf: - $ref: '#/components/schemas/handlers.ErrorDetails' description: >- Details provides optional structured error context (field errors, etc.) message: description: Message is the human-readable error description example: Invalid request parameters type: string type: object handlers.ErrUnauthorizedResponse: properties: code: description: Code is the machine-readable error code example: unauthorized type: string details: allOf: - $ref: '#/components/schemas/handlers.ErrorDetails' description: Details provides optional structured error context message: description: Message is the human-readable error description example: Missing or invalid credentials type: string type: object handlers.ErrForbiddenResponse: properties: code: description: Code is the machine-readable error code example: forbidden type: string details: allOf: - $ref: '#/components/schemas/handlers.ErrorDetails' description: Details provides optional structured error context message: description: Message is the human-readable error description example: Insufficient permissions for this action type: string type: object handlers.ErrNotFoundResponse: properties: code: description: Code is the machine-readable error code example: not_found type: string details: allOf: - $ref: '#/components/schemas/handlers.ErrorDetails' description: Details provides optional structured error context message: description: Message is the human-readable error description example: Resource not found type: string type: object handlers.ErrUnsupportedMediaTypeResponse: properties: code: description: Code is the machine-readable error code example: unsupported_media_type type: string details: allOf: - $ref: '#/components/schemas/handlers.ErrorDetails' description: Details provides optional structured error context message: description: Message is the human-readable error description example: Content-Type must be application/json type: string type: object handlers.ErrInternalResponse: properties: code: description: Code is the machine-readable error code example: internal_error type: string message: description: Message is the human-readable error description example: An internal error occurred type: string type: object handlers.SimulateDraftRule: properties: actions: description: >- Actions to execute when the condition matches (must be non-empty). Same flattened structure as rule create: each action has a `type` field that determines which other fields are relevant. items: $ref: '#/components/schemas/models.RuleAction' minItems: 1 type: array condition: description: CEL expression that determines when the rule fires example: event.type == 'purchase' minLength: 1 type: string name: description: Display name echoed back in the response. Defaults to "Draft rule". example: Purchase Reward maxLength: 255 minLength: 1 type: string required: - actions - condition type: object handlers.SimulateEvaluation: properties: matched: description: Whether the condition evaluated to true example: true type: boolean reason: description: Error detail when status is "condition_failed" example: 'no such key: amount' type: string results: description: >- Per-action outcomes with resolved amounts, projected counter values, and asset symbols. Present only when matched is true. example: - action: amount: ${{ event.amount * 10 }} asset_id: 550e8400-e29b-41d4-a716-446655440002 type: CREDIT result: amount: '750' asset_symbol: POINTS description: Credit 750 POINTS to participant items: type: object type: array status: description: >- "evaluated" on success, or "condition_failed" if the CEL expression errored example: evaluated type: string type: object handlers.SimulateRuleInfo: properties: condition: description: CEL expression that was evaluated example: event.type == 'purchase' && event.amount > 0 type: string id: description: Unique identifier for the rule example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string name: description: Display name example: Purchase Reward type: string order: description: Evaluation sequence position example: 100 type: integer stop_after_match: description: Whether this rule stops subsequent evaluation on match example: false type: boolean type: object models.RuleWarning: properties: code: description: >- Machine-readable warning category, e.g. RuleWarningCodeUnknownStateKey. example: unknown_state_key type: string key: description: The referenced key, as written in the condition. example: purchaseCnt type: string kind: description: >- State kind: StateKindCounter, StateKindTag, StateKindAttribute, or StateKindAlias. example: counter type: string message: description: >- Human-readable explanation (includes the suggestion when one exists). example: >- unknown counter "purchaseCnt" — no rule in this program writes it; did you mean "purchase_count"? type: string scope: description: >- State scope of the reference: StateScopeParticipant, StateScopeProgram, or StateScopeGroup. example: participant type: string suggestion: description: Closest known key, when a near-match exists. Empty otherwise. example: purchase_count type: string type: object handlers.ErrorDetails: description: >- Optional structured details about the error. Always a JSON object: a `fields` array for validation errors, or flat field/reason/expected/received properties for other input errors. properties: expected: description: Expected value or format (non-validation input errors) example: uuid type: string field: description: Field name that caused the error (non-validation input errors) example: asset_id type: string fields: description: >- Fields lists each offending input field on validation_error responses. items: $ref: '#/components/schemas/handlers.ErrorFieldDetail' type: array reason: description: Machine-readable reason code (non-validation input errors) example: invalid type: string received: description: Value that was received (non-validation input errors) example: not-a-uuid type: string type: object models.RuleAction: properties: allow_negative: description: >- Allow debit to overdraw and create a negative balance when funds are insufficient. DEBIT only. Defaults to false. example: false type: boolean amount: description: >- Static numeric string (e.g. "100") or a ${{ }} CEL expression returning a number (e.g. "${{ event.amount * 0.03 }}"). Legacy unmarked expressions remain supported for stored-rule compatibility but are deprecated for new rules. example: ${{ event.amount * 0.03 }} type: string asset_id: description: Asset to operate on example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string bucket: description: >- Balance bucket to target: AVAILABLE or HELD. Defaults to AVAILABLE for most actions, HELD for RELEASE. example: AVAILABLE type: string delay: description: >- How long to wait before firing the scheduled event; h/d/w units (e.g. "24h", "7d"). SCHEDULE_EVENT only. example: 24h type: string description: description: Context string recorded on the ledger entry example: Purchase reward type: string event_name: description: >- Event type to inject. For SCHEDULE_EVENT: fires after the delay expires. For BROADCAST: fans out to all participants immediately. example: check_status type: string expires_at: description: >- When the lot/tier expires. CREDIT: lot becomes unusable (LOT-mode assets). SET_TIER: tier assignment expires. Accepts an RFC3339 timestamp or a duration string with h/d/w units (e.g. "365d", "12w", "8760h"). example: 365d format: date-time type: string key: description: Counter or attribute key name example: purchase_count type: string level: description: Tier level within the track (e.g. "gold", "platinum") example: gold type: string matures_at: description: >- When the credited lot becomes usable (CREDIT only, LOT-mode assets). Accepts an RFC3339 timestamp or a duration string with h/d/w units (e.g. "30d", "720h"). example: 30d format: date-time type: string payload: description: >- Additional data included with the event when it fires. String values may embed ${{ }} CEL expressions (at any nesting depth, values only), resolved against the triggering rule's context when the action executes. type: object reference_id: description: >- Correlation ID for hold/release correlation and auth/settle reconciliation (LOT mode only). Static literal (e.g. "auth_12345") or ${{ }} CEL expression (e.g. "${{ event.authorization_id }}"). example: ${{ event.authorization_id }} type: string reset_after: description: >- Auto-reset duration for COUNTER actions. The counter resets to 0 after this duration elapses since the last reset; h/d/w units (e.g. "30d", "720h"). Send an empty string to remove auto-reset. example: 30d type: string tag: description: Tag name to add (TAG) or remove (UNTAG) example: VIP type: string target: allOf: - $ref: '#/components/schemas/models.ActionTarget' description: >- Alternate recipient for this action. Defaults to the event's participant. Supported for CREDIT, DEBIT, TAG, UNTAG, COUNTER, SET_ATTRIBUTE, SET_TIER. tier: description: Tier track name (e.g. "status", "loyalty") example: status type: string type: description: >- Action kind. Valid values: CREDIT, DEBIT, HOLD, RELEASE, FORFEIT, VOID_HOLD, TAG, UNTAG, COUNTER, SET_ATTRIBUTE, SET_TIER, SCHEDULE_EVENT, BROADCAST example: CREDIT type: string value: description: >- COUNTER: static numeric string or ${{ }} CEL expression. SET_ATTRIBUTE: literal string or ${{ }} CEL expression. example: '1' type: string type: object handlers.ErrorFieldDetail: description: >- A single field-level error: which input field failed, why, and (where known) the expected and received values. properties: expected: description: >- Expected value or format. Usually a string; for "one of" constraints it is an array of the allowed values. field: description: Field name that caused the error example: amount type: string message: description: Human-readable explanation (validation errors only) example: This field is required type: string reason: description: Machine-readable reason code example: required type: string received: description: Value that was received example: '-10.00' type: string type: object models.ActionTarget: properties: external_id: description: >- ExternalID is a ${{ }} CEL expression that evaluates to an external_id string. Cannot be combined with ID or ParticipantID. Example: "${{ event.referrer_id }}" where referrer_id contains an external_id like "user_123" example: ${{ event.referrer_id }} type: string id: description: >- ID is the public entity ID: participant_id for PARTICIPANT, group_id for GROUP. example: 550e8400-e29b-41d4-a716-446655440000 format: uuid type: string participant_id: description: >- ParticipantID is a ${{ }} CEL expression that evaluates to a participant UUID string. Cannot be combined with ID or ExternalID. Example: "${{ event.recipient_id }}" where recipient_id contains a participant UUID example: ${{ event.recipient_id }} type: string type: description: >- Type is the entity type: PARTICIPANT, GROUP, or PROGRAM. Optional when using id or dynamic ID fields (defaults to PARTICIPANT). example: PARTICIPANT type: string type: object securitySchemes: ApiKeyAuth: description: API key passed in the X-API-Key header. in: header name: X-API-Key type: apiKey BearerAuth: description: Bearer token passed in the Authorization header (e.g. "Bearer sk_..."). in: header name: Authorization type: apiKey ````