Recipes

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 - the attributes and parameters it declares. A rule that does not exist, or that references a name this recipe does not declare, is refused with the offending rules.N.rule_id in details.

POST

watch

management

recipes

Create a recipe

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,
      "preempts": "FLAG"
    }
  ],
  "attributes": [
    "plan_tier",
    "account_age_days"
  ],
  "parameters": {
    "blocked_countries": "RU,BY",
    "max_attempts": "5"
  }
}
'

import requests

url = "https://api.prelude.dev/v2/watch/management/recipes"

payload = {
    "name": "signup_proxy_abuse",
    "status": "SHADOW",
    "threshold": 70,
    "rules": [
        {
            "rule_id": "rul_01jc0t6fwwfgfsq1md24mhyztj",
            "weight": 40,
            "preempts": "FLAG"
        }
    ],
    "attributes": ["plan_tier", "account_age_days"],
    "parameters": {
        "blocked_countries": "RU,BY",
        "max_attempts": "5"
    }
}
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({
    name: 'signup_proxy_abuse',
    status: 'SHADOW',
    threshold: 70,
    rules: [{rule_id: 'rul_01jc0t6fwwfgfsq1md24mhyztj', weight: 40, preempts: 'FLAG'}],
    attributes: ['plan_tier', 'account_age_days'],
    parameters: {blocked_countries: 'RU,BY', max_attempts: '5'}
  })
};

fetch('https://api.prelude.dev/v2/watch/management/recipes', 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://api.prelude.dev/v2/watch/management/recipes",
  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([
    'name' => 'signup_proxy_abuse',
    'status' => 'SHADOW',
    'threshold' => 70,
    'rules' => [
        [
                'rule_id' => 'rul_01jc0t6fwwfgfsq1md24mhyztj',
                'weight' => 40,
                'preempts' => 'FLAG'
        ]
    ],
    'attributes' => [
        'plan_tier',
        'account_age_days'
    ],
    'parameters' => [
        'blocked_countries' => 'RU,BY',
        'max_attempts' => '5'
    ]
  ]),
  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://api.prelude.dev/v2/watch/management/recipes"

	payload := strings.NewReader("{\n  \"name\": \"signup_proxy_abuse\",\n  \"status\": \"SHADOW\",\n  \"threshold\": 70,\n  \"rules\": [\n    {\n      \"rule_id\": \"rul_01jc0t6fwwfgfsq1md24mhyztj\",\n      \"weight\": 40,\n      \"preempts\": \"FLAG\"\n    }\n  ],\n  \"attributes\": [\n    \"plan_tier\",\n    \"account_age_days\"\n  ],\n  \"parameters\": {\n    \"blocked_countries\": \"RU,BY\",\n    \"max_attempts\": \"5\"\n  }\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://api.prelude.dev/v2/watch/management/recipes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"signup_proxy_abuse\",\n  \"status\": \"SHADOW\",\n  \"threshold\": 70,\n  \"rules\": [\n    {\n      \"rule_id\": \"rul_01jc0t6fwwfgfsq1md24mhyztj\",\n      \"weight\": 40,\n      \"preempts\": \"FLAG\"\n    }\n  ],\n  \"attributes\": [\n    \"plan_tier\",\n    \"account_age_days\"\n  ],\n  \"parameters\": {\n    \"blocked_countries\": \"RU,BY\",\n    \"max_attempts\": \"5\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/watch/management/recipes")

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  \"name\": \"signup_proxy_abuse\",\n  \"status\": \"SHADOW\",\n  \"threshold\": 70,\n  \"rules\": [\n    {\n      \"rule_id\": \"rul_01jc0t6fwwfgfsq1md24mhyztj\",\n      \"weight\": 40,\n      \"preempts\": \"FLAG\"\n    }\n  ],\n  \"attributes\": [\n    \"plan_tier\",\n    \"account_age_days\"\n  ],\n  \"parameters\": {\n    \"blocked_countries\": \"RU,BY\",\n    \"max_attempts\": \"5\"\n  }\n}"

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

{
  "id": "rcp_01jc0t6fwwfgfsq1md24mhyztj",
  "name": "signup_proxy_abuse",
  "catalog_version": 1,
  "status": "DRAFT",
  "threshold": 70,
  "rules": [
    {
      "rule_id": "rul_01jc0t6fwwfgfsq1md24mhyztj",
      "weight": 40,
      "preempts": "FLAG"
    }
  ],
  "attributes": [
    "plan_tier",
    "account_age_days"
  ],
  "parameters": {
    "blocked_countries": "RU,BY",
    "max_attempts": "5"
  }
}

{
  "code": "invalid_recipe",
  "message": "The provided recipe is invalid. See `details` field for more information.",
  "type": "bad_request",
  "param": "recipe",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a"
}

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, "preempts": "FLAG" }
  ],
  "attributes": ["plan_tier"],
  "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.

Preempting rules

preempts 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 preempting rule; it is the only thing that accounts for a recipe reporting a score under its threshold and flagging anyway.

Attributes 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:

	`attributes`	`parameters`
Referenced as	`attr.<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.

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 attr. or param. names this recipe doesn’t declare
a managed rule reading any attr. or param. name at all - Prelude’s rules read 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

attributes

string[]

The request-level facts this recipe's rules may read, declared by key and referenced in an expression as attr.<key>. Values arrive with each evaluation.

A key is lower snake_case, at most 64 characters, and at most 32 may be declared. An attribute a rule reads and a recipe does not declare is a compile error, reported against that rule.

Example:

["plan_tier", "account_age_days"]

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.

Keys follow the same format as attributes, and at most 32 may be declared. Values are strings - the only type either supports today.

Show child attributes

Example:

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

Response

Created

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"

catalog_version

integer<int64>

required

The version of the Prelude signal catalog this recipe's rules are compiled against, stamped by the server when the recipe is created or replaced. It is what stops a catalog that later grows or deprecates entries from silently changing what this recipe means.

Example:

1

status

enum<string>

required

Available options:

DRAFT,

SHADOW,

LIVE,

INACTIVE

threshold

integer<int64>

required

Example:

70

rules

object[]

required

Show child attributes

attributes

string[]

Example:

["plan_tier", "account_age_days"]

parameters

object

Show child attributes

Example:

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

Create a recipe

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,
      "preempts": "FLAG"
    }
  ],
  "attributes": [
    "plan_tier",
    "account_age_days"
  ],
  "parameters": {
    "blocked_countries": "RU,BY",
    "max_attempts": "5"
  }
}
'

import requests

url = "https://api.prelude.dev/v2/watch/management/recipes"

payload = {
    "name": "signup_proxy_abuse",
    "status": "SHADOW",
    "threshold": 70,
    "rules": [
        {
            "rule_id": "rul_01jc0t6fwwfgfsq1md24mhyztj",
            "weight": 40,
            "preempts": "FLAG"
        }
    ],
    "attributes": ["plan_tier", "account_age_days"],
    "parameters": {
        "blocked_countries": "RU,BY",
        "max_attempts": "5"
    }
}
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({
    name: 'signup_proxy_abuse',
    status: 'SHADOW',
    threshold: 70,
    rules: [{rule_id: 'rul_01jc0t6fwwfgfsq1md24mhyztj', weight: 40, preempts: 'FLAG'}],
    attributes: ['plan_tier', 'account_age_days'],
    parameters: {blocked_countries: 'RU,BY', max_attempts: '5'}
  })
};

fetch('https://api.prelude.dev/v2/watch/management/recipes', 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://api.prelude.dev/v2/watch/management/recipes",
  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([
    'name' => 'signup_proxy_abuse',
    'status' => 'SHADOW',
    'threshold' => 70,
    'rules' => [
        [
                'rule_id' => 'rul_01jc0t6fwwfgfsq1md24mhyztj',
                'weight' => 40,
                'preempts' => 'FLAG'
        ]
    ],
    'attributes' => [
        'plan_tier',
        'account_age_days'
    ],
    'parameters' => [
        'blocked_countries' => 'RU,BY',
        'max_attempts' => '5'
    ]
  ]),
  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://api.prelude.dev/v2/watch/management/recipes"

	payload := strings.NewReader("{\n  \"name\": \"signup_proxy_abuse\",\n  \"status\": \"SHADOW\",\n  \"threshold\": 70,\n  \"rules\": [\n    {\n      \"rule_id\": \"rul_01jc0t6fwwfgfsq1md24mhyztj\",\n      \"weight\": 40,\n      \"preempts\": \"FLAG\"\n    }\n  ],\n  \"attributes\": [\n    \"plan_tier\",\n    \"account_age_days\"\n  ],\n  \"parameters\": {\n    \"blocked_countries\": \"RU,BY\",\n    \"max_attempts\": \"5\"\n  }\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://api.prelude.dev/v2/watch/management/recipes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"signup_proxy_abuse\",\n  \"status\": \"SHADOW\",\n  \"threshold\": 70,\n  \"rules\": [\n    {\n      \"rule_id\": \"rul_01jc0t6fwwfgfsq1md24mhyztj\",\n      \"weight\": 40,\n      \"preempts\": \"FLAG\"\n    }\n  ],\n  \"attributes\": [\n    \"plan_tier\",\n    \"account_age_days\"\n  ],\n  \"parameters\": {\n    \"blocked_countries\": \"RU,BY\",\n    \"max_attempts\": \"5\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.prelude.dev/v2/watch/management/recipes")

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  \"name\": \"signup_proxy_abuse\",\n  \"status\": \"SHADOW\",\n  \"threshold\": 70,\n  \"rules\": [\n    {\n      \"rule_id\": \"rul_01jc0t6fwwfgfsq1md24mhyztj\",\n      \"weight\": 40,\n      \"preempts\": \"FLAG\"\n    }\n  ],\n  \"attributes\": [\n    \"plan_tier\",\n    \"account_age_days\"\n  ],\n  \"parameters\": {\n    \"blocked_countries\": \"RU,BY\",\n    \"max_attempts\": \"5\"\n  }\n}"

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

{
  "id": "rcp_01jc0t6fwwfgfsq1md24mhyztj",
  "name": "signup_proxy_abuse",
  "catalog_version": 1,
  "status": "DRAFT",
  "threshold": 70,
  "rules": [
    {
      "rule_id": "rul_01jc0t6fwwfgfsq1md24mhyztj",
      "weight": 40,
      "preempts": "FLAG"
    }
  ],
  "attributes": [
    "plan_tier",
    "account_age_days"
  ],
  "parameters": {
    "blocked_countries": "RU,BY",
    "max_attempts": "5"
  }
}

{
  "code": "invalid_recipe",
  "message": "The provided recipe is invalid. See `details` field for more information.",
  "type": "bad_request",
  "param": "recipe",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a"
}

Documentation

API Reference

Management API

Assemble rules into a scored decision

Start in `SHADOW`

Preempting rules

Attributes and parameters

What is validated

Authorizations

Body

Response

​Start in SHADOW

​Preempting rules

​Attributes and parameters

​What is validated

Authorizations

Body

Response

Start in `SHADOW`

Preempting rules

Attributes and parameters

What is validated