Docs / API: Alert rules

Create a rule

Creates an alert rule and returns its signing secret once. An account can hold 10 rules. cooldown_seconds is how long the rule waits after it fires, from 60 to 86400, default 300. format is json, discord or telegram. A Telegram rule needs no url.

POST/api/v1/rules

Property	Value
Authentication	Required. Send `Authorization: Bearer <key>`.
Rate-limit cost	1 unit
Status	Live

#Request body

JSON

{
  "name": "Large stablecoin moves",
  "expression": "usd >= 5m and token in [\"USDC\",\"USDT\"]",
  "url": "https://example.com/hooks/farbeam",
  "format": "json"
}

#Request

curl -s -X POST "https://farbeamlabs.com/api/v1/rules" \
  -H "Authorization: Bearer $FARBEAM_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Large stablecoin moves", "expression": "usd >= 5m and token in [\"USDC\",\"USDT\"]", "url": "https://example.com/hooks/farbeam", "format": "json"}'

const res = await fetch("https://farbeamlabs.com/api/v1/rules", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.FARBEAM_KEY}`, "content-type": "application/json" },
  body: JSON.stringify({"name": "Large stablecoin moves", "expression": "usd >= 5m and token in [\"USDC\",\"USDT\"]", "url": "https://example.com/hooks/farbeam", "format": "json"})
});
const { data, meta, error } = await res.json();
if (error) throw new Error(`${error.code}: ${error.message}`);
console.log(data);

import os, requests

res = requests.post(
    "https://farbeamlabs.com/api/v1/rules",
    headers={"Authorization": f"Bearer {os.environ['FARBEAM_KEY']}"},
    json={'name': 'Large stablecoin moves', 'expression': 'usd >= 5m and token in ["USDC","USDT"]', 'url': 'https://example.com/hooks/farbeam', 'format': 'json'},
    timeout=30,
)
body = res.json()
if "error" in body:
    raise RuntimeError(body["error"]["code"])
print(body["data"])

You can send this request now in the API playground.

#Response

This response is real. It was captured from the running API when this page was built. Arrays are cut to two items.

JSON

{
  "data": {
    "id": "rule_000000000000",
    "name": "Large stablecoin moves",
    "expression": "usd >= 5m and token in [\"USDC\",\"USDT\"]",
    "url": "https://example.com/hooks/farbeam",
    "format": "json",
    "cooldown_seconds": 300,
    "last_fired_at": null,
    "enabled": true,
    "created_at": "2026-11-04T20:10:58.171Z",
    "consecutive_failures": 0,
    "signing_secret": "fbs_000000000000000000000000000000000000000000000000"
  },
  "meta": {
    "request_id": "req_ad07c678b321",
    "as_of": "2026-11-04T20:10:58.171Z"
  }
}

#Fields

Field	Type	Description
`name`	string	Required. 1 to 80 characters.
`expression`	string	Required. A Beamline expression of up to 1,000 characters.
`url`	string	Required. Public HTTPS URL on port 443.
`format`	string	`json` (default) or `discord`.
`enabled`	boolean	Default true.
`data.signing_secret`	string	Response field. Shown once. Use it to verify signatures.

#Errors

HTTP	Code	Meaning
401	`missing_key`	The request has no key.
422	`invalid_rule`	The expression did not parse. The message gives the position.
422	`invalid_url`	The webhook URL is not a public HTTPS URL.
409	`rule_limit`	The key already holds 10 rules.

All errors share one format. See errors.

PreviousList rules NextGet a rule