---
title: "Create or update an alert rule"
method: POST
path: "/api/v1/alerts"
tags: ["Write"]
---

# Create or update an alert rule

`POST /api/v1/alerts`

## Request

- Base URL: `https://api.trysonar.app`
- URL: `https://api.trysonar.app/api/v1/alerts`
- Auth: HTTP bearer

Upserts on (type, scope_app_id). Omit threshold for the per-type default; omit scope_app_id for an org-wide rule. Requires an Indie or Agency plan and a write-scope API key.

## Request body

- object
  - `type` 'rank_drop' | 'rank_gain' | 'entered_top10' | 'left_top10' | 'new_ranking' | 'rating_drop' | 'review_spike' | 'competitor_change' | 'top_chart' | 'new_review', required
  - `scope_app_id` string, nullable: App UUID to scope to; null/omitted = all tracked apps
  - `threshold` integer, nullable: null/omitted = per-type default. For top_chart: the rank cutoff (1-200, default 200). For new_review: the highest star rating that alerts (1-5, default 5 = every review)
  - `countries` string[], nullable: top_chart only: storefronts to watch (ISO 3166-1 alpha-2). Omit to keep the stored list; null/[] = the countries the org tracks keywords in
  - `cadence` 'instant' | 'hourly' | 'daily' | 'null', nullable: new_review only: email timing — instant (within ~5-10 minutes), hourly (at most one email per hour) or daily (the 08:30 UTC digest). Omit to keep the stored value (daily on create); sent with any other type → 400
  - `enabled` boolean

## Response `201`

The created/updated alert rule

- object
  - `data` object, required: Result payload — full field reference at https://trysonar.app/docs/api

## Other responses

- `400`: Unknown type, scope_app_id not tracked, or invalid countries/cadence
- `401`: Missing or invalid API key
- `403`: Plan or scope insufficient (workspace endpoints need an Indie or Agency plan; writes also need a write-scope key)
- `429`: Rate limited — see `error.reason`: daily_limit (Indie 1,000, Agency 5,000, trial 150 requests/day, resets 00:00 UTC; see `reset_at`), anonymous_daily_limit / batch_too_large (keyless free tier), store_rate_limited or concurrency_limit (transient, honor `retry_after_seconds`)
- `500`: Unexpected server error

---

[API](https://skmtc.dev/trysonar/apis/sonar-api.md) · [All operations](https://skmtc.dev/trysonar/apis/sonar-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trysonar/apis/sonar-api/revisions/bf1d31dadd5f?raw)