Rulesets

Simulate ruleset

Evaluates a caller-supplied test payload against the persisted ruleset addressed by — any lifecycle state (DRAFT / ACTIVE / INACTIVE) — and returns an evaluation trace. The ruleset’s own (schema, version) binding validates the payload and resolves rule field paths; the request carries no schema selector and no context. Requires the dedicated admin:rulesets:simulate scope. The simulation is inert — no decision record, no velocity counter increment, no blacklist push, no webhook, no lifecycle event, no backend invocation. Velocity counters are read live and never written, so two identical simulations may differ; the trace labels counter values as live-read.

POST

api

admin

rulesets

{id}

simulate

Simulate ruleset

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": {}
}'

import requests

url = "https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate"

payload = { "payload": {} }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({payload: {}})
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payload' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate"

	payload := strings.NewReader("{\n  \"payload\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payload\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payload\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "backend_results": [],
  "context": "checkout",
  "ruleset_id": "1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d",
  "ruleset_status": "DRAFT",
  "ruleset_version": 3,
  "schema": {
    "name": "transaction"
  },
  "simulated_at": "2026-07-25T12:00:00Z",
  "trace": [
    {
      "action": "REVIEW",
      "fields": [
        {
          "path": "$.transaction.amount",
          "value": 150
        }
      ],
      "name": "Review medium amount",
      "outcome": "fired",
      "rule_id": "r1",
      "type": "condition"
    },
    {
      "action": "BLOCK",
      "fields": [
        {
          "path": "$.transaction.amount",
          "value": 150
        }
      ],
      "name": "Block high amount",
      "outcome": "fired",
      "rule_id": "r2",
      "type": "condition"
    },
    {
      "action": "REVIEW",
      "name": "Review non-USD",
      "outcome": "not_evaluated",
      "rule_id": "r3",
      "skip_reason": "short_circuited",
      "type": "condition"
    }
  ],
  "verdict": "BLOCK",
  "verdict_suppressed": null
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "VALIDATION_ERROR",
  "code": 422,
  "validation_errors": [
    {
      "message": "must be a positive integer",
      "path": "limit"
    }
  ]
}

Authorizations

Authorization

string

header

required

HS256-signed JWT bearer token, obtained via the OAuth2 client-credentials grant (see Authentication).

Path Parameters

string

required

Ruleset ID

Body

application/json

payload

object

required

The test decision payload. Validates exactly as the live decision body does against the ruleset's bound (schema, version). A "context" key is ignored — routing is fixed by the ruleset addressed in the URL.

Response

Evaluation trace

Result of simulating a ruleset against a test payload. The trace is a superset of the decision response's triggered_rules — same entry vocabulary, extended to every rule of the ruleset with its outcome and the derivations behind it.

backend_results

BackendResult · object[]

required

One entry per backend rule that was reached, in the published BackendResult shape. Simulation never invokes a backend — decision is null, error is "not_simulated" (sibling of "insufficient_context" — backend skipped, no call made), latency_ms is null. Where the instance has the Link capability disabled, the live path makes no call either and records "backend_capability_disabled" with latency_ms 0; the trace renders that entry instead, so it reads as the live one would.

Show child attributes

context

string

required

The simulated ruleset's context routing key.

ruleset_id

string<uuid>

required

ruleset_status

enum<string>

required

Available options:

DRAFT,

ACTIVE,

INACTIVE

ruleset_version

integer

required

schema

SchemaBinding · object

required

A ruleset's declared (schema, version) pair. name references a registry entry; version is required for custom schemas and absent for built-ins, whose version is implicit and advances only via Specter releases. Set at ruleset creation and immutable for the life of that ruleset version — rebinding a context means publishing a new ruleset version with the new binding and activating it. Rulesets that predate the registry surface the launch-backfilled transaction binding.

Show child attributes

simulated_at

string<date-time>

required

trace

TraceEntry · object[]

required

One entry per rule of the ruleset, in published evaluation order (rules-array order).

Show child attributes

verdict

enum<string> | null

required

Simulated verdict — same semantics as the live decision enum. BLOCK terminates on first match, REVIEW accumulates, ALLOW is the default when nothing fires. PROVISIONAL is unreachable by simulation (no backend is ever invoked). Null exactly when verdict_suppressed is non-null.

Available options:

ALLOW,

REVIEW,

BLOCK

verdict_suppressed

object | null

required

Present when the run cannot state the verdict a live decision would return. Reaching a live, synchronous backend rule suppresses it (backend_reached) — the backend is not invoked and its answer could change everything after it, so the remaining rules render not_evaluated. An async backend rule suppresses only a verdict that would otherwise be ALLOW (async_backend_reached), where the live path returns PROVISIONAL. Shadow rules (live false) and rules on an instance with the Link capability disabled never suppress.

Show child attributes

warnings

SimulationWarning · object[]

Authoring soft-warns — advisory only, never affecting the verdict. Emitted e.g. when credential.pan and credential.masked_pan both populate the same BIN attribute with differing values (code bin_attribute_divergence, paths naming both field paths).

Show child attributes

⌘I

Simulate ruleset

curl --request POST \
  --url https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "payload": {}
}'

import requests

url = "https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate"

payload = { "payload": {} }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({payload: {}})
};

fetch('https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payload' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate"

	payload := strings.NewReader("{\n  \"payload\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payload\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{instance}.{env}.on-hellgate.cloud/api/admin/rulesets/{id}/simulate")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payload\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "backend_results": [],
  "context": "checkout",
  "ruleset_id": "1f2e3d4c-5b6a-4978-8c0d-1e2f3a4b5c6d",
  "ruleset_status": "DRAFT",
  "ruleset_version": 3,
  "schema": {
    "name": "transaction"
  },
  "simulated_at": "2026-07-25T12:00:00Z",
  "trace": [
    {
      "action": "REVIEW",
      "fields": [
        {
          "path": "$.transaction.amount",
          "value": 150
        }
      ],
      "name": "Review medium amount",
      "outcome": "fired",
      "rule_id": "r1",
      "type": "condition"
    },
    {
      "action": "BLOCK",
      "fields": [
        {
          "path": "$.transaction.amount",
          "value": 150
        }
      ],
      "name": "Block high amount",
      "outcome": "fired",
      "rule_id": "r2",
      "type": "condition"
    },
    {
      "action": "REVIEW",
      "name": "Review non-USD",
      "outcome": "not_evaluated",
      "rule_id": "r3",
      "skip_reason": "short_circuited",
      "type": "condition"
    }
  ],
  "verdict": "BLOCK",
  "verdict_suppressed": null
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "NOT_FOUND",
  "code": 404,
  "message": "The requested resource does not exist"
}

{
  "classifier": "VALIDATION_ERROR",
  "code": 422,
  "validation_errors": [
    {
      "message": "must be a positive integer",
      "path": "limit"
    }
  ]
}

Getting Started

Decisions

Lifecycle Events

Admin

Simulate ruleset

Authorizations

Path Parameters

Body

Response