Assemble rules into a scored decision

Beta. The request and response shapes may still change.

Assemble rules into a scored decision: each rule carries a weight, the weights of the rules that trigger are summed, and the recipe flags when the total reaches the threshold.

Every rule associated here is read and compiled against this recipe’s own environment. A rule that does not exist, or that references a parameter this recipe does not declare, is refused with the offending rules.N.rule_id in details.

POST /v2/watch/management/recipes

Create a recipe

cURL

curl --request POST \
  --url https://api.prelude.dev/v2/watch/management/recipes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "signup_proxy_abuse",
  "status": "SHADOW",
  "threshold": 70,
  "rules": [
    {
      "rule_id": "rul_01jc0t6fwwfgfsq1md24mhyztj",
      "weight": 40,
      "overrides": "FLAG"
    }
  ],
  "parameters": {
    "blocked_countries": "RU,BY",
    "max_attempts": "5"
  }
}
'

201

{
  "id": "rcp_01jc0t6fwwfgfsq1md24mhyztj",
  "name": "signup_proxy_abuse",
  "status": "DRAFT",
  "threshold": 70,
  "rules": [
    {
      "rule_id": "rul_01jc0t6fwwfgfsq1md24mhyztj",
      "weight": 40,
      "overrides": "FLAG"
    }
  ],
  "parameters": {
    "blocked_countries": "RU,BY",
    "max_attempts": "5"
  }
}

A recipe is where rules become a verdict. Each rule carries a weight; the weights of the rules that trigger are summed; the recipe flags when the total reaches the threshold.

{
  "name": "signup_proxy_abuse",
  "status": "SHADOW",
  "threshold": 70,
  "rules": [
    { "rule_id": "rul_01jc0t6fwwfgfsq1md24mhyztj", "weight": 40 },
    { "rule_id": "rul_01jd1u7gxxghgtr2ne35nizauk", "weight": 30 },
    { "rule_id": "rul_01je2v8hyyhihus3of46ojabvl", "weight": 50, "overrides": "FLAG" }
  ],
  "parameters": { "blocked_countries": "RU,BY" }
}

Start in SHADOW

A threshold set without evidence is a guess. SHADOW evaluates against live traffic and reports its verdict without it counting toward the evaluation-level answer, which is the only way to see what a threshold would have done before it decides anything. Move to LIVE when the numbers justify it.

DRAFT and INACTIVE are the two ways a recipe exists without being in service - one not yet put into it, one taken back out. A flow referencing either runs its other recipes and reports nothing for that one: it wasn’t asked, which is not the same as having passed.

Overriding rules

overrides makes a rule’s outcome the recipe’s verdict, bypassing the score. Use it for a condition that is conclusive on its own.

Expressing that through weights instead means picking a number above every threshold the recipe might later be given - a fact about the recipe’s arithmetic rather than about the rule, which quietly stops being true when the threshold moves.

The weight still applies and the score is still reported. In an evaluation, determined_by references the overriding rule; it is the only thing that accounts for a recipe reporting a score under its threshold and flagging anyway.

If overriding rules with different verdicts both trigger, PASS wins over FLAG, whatever the order of rules. Several triggered rules with the same verdict are not a conflict: determined_by names the first to trigger. See Conflicting overrides.

Your own signals and parameters

Both let a rule read something the signal catalog doesn’t know. They differ in how long a value lasts, and that difference decides everything else:

	Your own signals	parameters
Referenced as	signal.ext.<key>	param.<key>
Value arrives	With each evaluation, in the request	Here, when the recipe is written
Changes	Per request	Only when the recipe is replaced
If absent	Missing evidence: rules reading it report NOT_EVALUATED	Cannot be absent - the recipe would not have saved
Good for	Plan tier, account age, cart total	A country list, a limit, a tuning constant

Keys are lower snake_case, at most 64 characters, declared without their namespace. At most 32 of each. Values are strings - the only type either supports today.

You don’t list your own signals here: the recipe reads them off its rules. Send their values in signals.ext when you evaluate a flow.

What is validated

Every rule associated here is read and compiled in this recipe’s environment, which is what catches a mismatch between a rule and the recipe using it:

• a rule identifier that doesn’t exist, or belongs to no tier you can reach
• a rule reading param. names this recipe doesn’t declare
• a managed rule reading any signal.ext. or param. name at all - Prelude’s rules read Prelude signals only, and one pinned to your recipe would stop being shared

Failures come back together, one details entry per rule, keyed rules.N.rule_id - so a recipe with three problems takes one round trip to fix, not three. A managed rule that won’t compile is reported as unusable without quoting its expression.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

name · string · required

Maximum string length: 128

Example:

"signup_proxy_abuse"

status · enum<string> · required

Whether the recipe takes part in an evaluation, and whether its verdict counts.

• DRAFT - Not yet in service. It does not evaluate.
• SHADOW - Evaluates and is reported, so you can watch a threshold against live traffic before trusting it.
• LIVE - Evaluates, and its verdict counts toward the evaluation-level answer.
• INACTIVE - Taken back out of service. It does not evaluate.

Available options: DRAFT, SHADOW, LIVE, INACTIVE

Example:

"SHADOW"

threshold · integer<int64> · required

The score at which the recipe flags. The weights of the rules that triggered are summed, and the recipe flags when the total reaches this value. A threshold of 0 flags every evaluation.

Example:

70

rules · object[] · required

The rules this recipe scores over, with their weights. At least one is required.

Minimum array length: 1

Show child attributes

parameters · object

This recipe's configuration: keys and their values, referenced in an expression as param.<key>, fixed until the recipe is replaced. Use them for the country list or the limit a shared rule should apply here, so the same rule can serve two recipes tuned differently.

A key is lower snake_case, at most 64 characters, and at most 32 may be declared. Values are strings - the only type either supports today.

Every key needs a value. An empty value is refused - omit the key instead.

Show child attributes

Example:

{
  "blocked_countries": "RU,BY",
  "max_attempts": "5"
}

Response

201

application/json

Created

id · string · required

The recipe identifier. Reference it in a flow's recipes to run it.

Example:

"rcp_01jc0t6fwwfgfsq1md24mhyztj"

name · string · required

Example:

"signup_proxy_abuse"

status · enum<string> · required

Available options: DRAFT, SHADOW, LIVE, INACTIVE

threshold · integer<int64> · required

Example:

70

rules · object[] · required

Show child attributes

parameters · object

Show child attributes

Example:

{
  "blocked_countries": "RU,BY",
  "max_attempts": "5"
}