Recipes

Replace a recipe

Beta. The request and response shapes may still change.

Overwrite a recipe in place. The body is the whole recipe, not a patch: rules, attributes and parameters you omit are cleared.

The submitted recipe is validated exactly as a creation is, and the stored catalog_version is re-stamped to the latest - an edit re-pins the recipe to today’s signal vocabulary. Moving a recipe between DRAFT, SHADOW, LIVE and INACTIVE is this endpoint too.

PUT

watch

management

recipes

{recipe_id}

Replace a recipe

curl --request PUT \
  --url https://api.prelude.dev/v2/watch/management/recipes/{recipe_id} \
  --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/{recipe_id}"

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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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/{recipe_id}', 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/{recipe_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  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/{recipe_id}"

	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("PUT", 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.put("https://api.prelude.dev/v2/watch/management/recipes/{recipe_id}")
  .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/{recipe_id}")

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

request = Net::HTTP::Put.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_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

The body is the whole recipe, not a patch: rules, attributes and parameters you omit are cleared. Read the recipe first if you are changing one field. This is also how a recipe moves through its lifecycle - send the same body with a new status to promote a SHADOW recipe to LIVE, or to take a LIVE one back to INACTIVE.

Authorizations

Authorization

string

header

required

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

Path Parameters

recipe_id

string

required

The recipe identifier.

Example:

"rcp_01jc0t6fwwfgfsq1md24mhyztj"

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

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"
}

Replace a recipe

curl --request PUT \
  --url https://api.prelude.dev/v2/watch/management/recipes/{recipe_id} \
  --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/{recipe_id}"

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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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/{recipe_id}', 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/{recipe_id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  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/{recipe_id}"

	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("PUT", 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.put("https://api.prelude.dev/v2/watch/management/recipes/{recipe_id}")
  .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/{recipe_id}")

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

request = Net::HTTP::Put.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_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

{
  "code": "invalid_phone_number",
  "message": "The provided phone number is invalid. Provide a valid E.164 phone number.",
  "type": "bad_request",
  "request_id": "3d19215e-2991-4a05-a41a-527314e6ff6a",
  "param": "phone_number"
}

Documentation

API Reference

Management API

Replace a recipe

Authorizations

Path Parameters

Body

Response