---
title: Create a semantic alert
description: Signed-in semantic alerts (#2304).
---
# Create a semantic alert

`POST https://api.releases.sh/v1/me/semantic-alerts`

Signed-in semantic alerts (#2304). Stores a freeform interest and email/webhook preferences. Matching runs after release.created for releases already on the caller's follow graph: one JEV decision per release, one question per enabled alert, notify when the matches-interest probability is at least the alert threshold (default 0.80, allowed 0.50–1.00). At most 5 alerts per account. Query text is user-private and is never written to Analytics Engine. Requires a Better Auth session or a user Bearer token (`relu_` or OAuth JWT); machine `relk_` tokens and anonymous callers are refused. Returns 404 when `semantic-alerts-enabled` is off. Body: `{ query, enabled?, threshold?, deliverEmail?, deliverWebhook?, webhookSubscriptionId? }`. `query` is required, trimmed, and at most 500 characters. Omitted `enabled` defaults to true, `threshold` to 0.8, `deliverEmail` to true, `deliverWebhook` to false.

**Auth:** Bearer token required.

**Request body** (`application/json`)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | yes | Freeform interest. Trimmed. User-private. |
| `enabled` | boolean | no |  |
| `threshold` | number | no |  |
| `deliverEmail` | boolean | no |  |
| `deliverWebhook` | boolean | no |  |
| `webhookSubscriptionId` | string \| null | no | One of the caller's webhook subscriptions. `null` clears the link on update. |

**Responses**

- `201` The created alert.
- `400` Invalid query, threshold, booleans, or webhookSubscriptionId
- `401` Sign-in required
- `404` Semantic alerts are disabled
- `429` Maximum semantic alerts per account reached

Full request and response schemas: [OpenAPI 3.1 spec](https://api.releases.sh/v1/openapi.json).