Alterscope Developer API

A metric that hovers near your threshold can cross it, fall back, and cross it again within minutes. Without noise control, that’s one notification per crossing. Three independent fields on every rule — set at creation or added later with a partial-merge PUT — cut that down before a message is ever sent.

These fields live on the rule itself (see Create and manage alert rules) — there’s no separate noise-control endpoint. All three are optional; omit them and the rule fires on every condition match, every time.

The three controls

Field	Unit	What it does
`cooldown_minutes`	minutes	After a firing, the rule cannot fire again for the same opportunity until this many minutes pass — even if the condition keeps matching.
`require_persistence_minutes`	minutes	The condition must hold continuously for this long before it counts as a fire. A one-tick blip that reverts a minute later never fires.
`dedupe_window_minutes`	minutes	If the rule would fire again with the same condition values as its last firing, and less than this many minutes have passed, the repeat is suppressed.

They apply in this order: persistence gates whether a fire is considered at all, then cooldown and dedupe gate whether that fire is actually delivered.

1. Cooldown — enforce a minimum gap between firings

curl

curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
     -H "Content-Type: application/json" \
     -X POST -d '{
       "name": "USDC APY drop",
       "data_source": "yield_radar",
       "asset_symbol": "USDC",
       "conditions": [{ "field": "apy", "operator": "lt", "value": 5.0 }],
       "message_template": "{{.asset_symbol}} APY fell to {{.apy}}%",
       "cooldown_minutes": 60
     }' \
  "https://api.alterscope.org/v1/alerts/rules"

With cooldown_minutes: 60, once this rule fires for a given opportunity, it won’t fire again for that same opportunity for an hour — regardless of how many times the APY dips below 5% and recovers in between. A different opportunity (a different asset/venue pair the rule also watches) has its own independent cooldown clock.

2. Persistence — require the condition to hold, not just touch

curl

curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
     -H "Content-Type: application/json" \
     -X PUT -d '{ "require_persistence_minutes": 15 }' \
  "https://api.alterscope.org/v1/alerts/rules/$RULE_ID"

require_persistence_minutes: 15 means the condition has to stay true for a continuous 15-minute stretch before the rule fires. If the APY drops below 5% and climbs back above it two minutes later, that dip never fires — it didn’t persist long enough. This is the field to reach for when a source is naturally noisy (perp funding rates, thin-liquidity APYs) and single-tick crossings aren’t actionable on their own.

3. Dedupe — collapse repeats of the same values

curl

curl -H "Authorization: Bearer $ALTERSCOPE_API_KEY" \
     -H "Content-Type: application/json" \
     -X PUT -d '{ "dedupe_window_minutes": 30 }' \
  "https://api.alterscope.org/v1/alerts/rules/$RULE_ID"

Cooldown suppresses any re-fire; dedupe only suppresses a re-fire that reports the same condition values as the previous one. Set both together when you want “at most one alert per half hour, and definitely not two identical ones back to back.”

Validation

All three fields reject negative values with 400:

{ "error": "require_persistence_minutes must be non-negative" }

The same applies to dedupe_window_minutes. There’s no upper bound enforced server-side — pick a window that matches how often the underlying data actually refreshes; a require_persistence_minutes longer than your data source’s polling interval will never be satisfiable.

Troubleshooting

A rule I expected to fire didn’t: check require_persistence_minutes first — a condition that flickers in and out never accumulates a persistent match. Pull GET /v1/alerts/events?rule_id=$RULE_ID&status=suppressed to see fires the platform held back and why.
I’m still getting near-duplicate alerts seconds apart: dedupe_window_minutes only collapses fires with identical condition values; if the underlying value is still moving (APY ticking down by 0.1% each time), each fire looks different and dedupe won’t merge them — use cooldown_minutes instead, which doesn’t care whether the values match.
400 on create or update: re-check for a negative value on require_persistence_minutes or dedupe_window_minutes — see Validation above.

​The three controls

​1. Cooldown — enforce a minimum gap between firings

​2. Persistence — require the condition to hold, not just touch

​3. Dedupe — collapse repeats of the same values

​Validation

​Troubleshooting

The three controls

1. Cooldown — enforce a minimum gap between firings

2. Persistence — require the condition to hold, not just touch

3. Dedupe — collapse repeats of the same values

Validation

Troubleshooting