---
title: "Create a price alert"
method: POST
path: "/v1/alerts"
tags: ["alerts"]
---

# Create a price alert

`POST /v1/alerts`

## Request

- Base URL: `https://api.goldprice.dev`
- URL: `https://api.goldprice.dev/v1/alerts`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Creates an alert on the plan's allowance. The signing secret is in this response only.

## Request body

- AlertBody
  - `url` string, required
  - `asset` 'XAU' | 'XAG' | 'HG', required
  - `kind` 'level_cross' | 'percent_move' | 'daily_close', required
  - `direction` 'above' | 'below' | 'either'
  - `level` number, nullable
  - `percent` number, nullable
  - `window` '1h' | '24h', nullable

## Response `201`

Successful Response

- AlertCreated
  - `id` string, required
  - `url` string, required
  - `rule` AlertRule, required
    - `asset` string, required
    - `kind` string, required
    - `direction` string, required
    - `level` number, nullable
    - `percent` number, nullable
    - `window` string, nullable
  - `created_at` string, required
  - `secret` string, required

## Other responses

- `400`: Bad request.
- `401`: Authentication failed.
- `403`: The caller's tier does not allow this request.
- `422`: Invalid body.
- `429`: Rate limit or quota exceeded. `error` is one of: `rate_limited` (keyless caller over the per-IP hourly cap, X-RateLimit-Scope anon-ip-hour), `rate_limit_exceeded` (API key over its per-minute limit, scope tier-rate-minute) or `quota_exceeded` (monthly quota used, scope tier-quota-month). Wait for Retry-After seconds before retrying; do not retry a monthly quota error automatically.
- `503`: A required backend or data source is temporarily unavailable.

## Changes

- **2026-11-03** `cb56f61da26c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/goldprice/apis/gold-api/changes/v1/alerts/post.md)

---

[API](https://skmtc.dev/goldprice/apis/gold-api.md) - [All operations](https://skmtc.dev/goldprice/apis/gold-api/llms.txt) - [OpenAPI document](https://skmtc.dev/goldprice/apis/gold-api/revisions/cb56f61da26c?raw)