---
title: "POST /api/v1/alerts"
method: POST
path: "/api/v1/alerts"
tags: ["formulas"]
---

# POST /api/v1/alerts

`POST /api/v1/alerts`

## Request

- Base URL: `https://api.blackforge.so` (the document declares no server; this is the origin it was published from)
- URL: `https://api.blackforge.so/api/v1/alerts`
- Auth: API key in header `x-api-key`

## Request body

- CreateAlertDto
  - `formulaId` string, required: The formula to watch (`fml_…`).
  - `direction` 'above' | 'below' | 'cross', required
  - `threshold` number, required: The value you set.
  - `hysteresis` number: How far back across the value the formula must move before it can notify again. Absolute, default 0.
  - `cooldownSeconds` number: Seconds before it can notify again, 60 to 86400. Default 900.
  - `email` boolean: Email the account's verified address. Default true. The address is never an argument.
  - `webhookUrl` string: An https URL we POST each notification to, signed with `x-blackforge-signature`. API keys only.

## Response `201`

Tells you when your formula crosses the value you set, by email to the account address and/or a signed https webhook. The webhook secret is returned once. Ultra only; any other plan gets 403 {"error":{"code":"plan_required","plan":"ultra","upgrade":"https://blackforge.so/pricing"}}.

---

[API](https://skmtc.dev/blackforge/apis/blackforge-data-api.md) · [All operations](https://skmtc.dev/blackforge/apis/blackforge-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/blackforge/apis/blackforge-data-api/revisions/04eadd230b1b?raw)