API Documentation

Everything you need to integrate StockAlert.pro into your applications

Alerts API

Create, manage, and monitor stock price alerts programmatically

Overview

The Alerts API allows you to create and manage stock price alerts that trigger when specific market conditions are met. Alerts can monitor price movements, technical indicators, and more.

Real-time Monitoring

Alerts are evaluated every minute during market hours

21 Alert Types

Price, technical, volume, fundamental, time, and dividend alerts

Flexible Notifications

Email, SMS, and webhook delivery

List Alerts

GET/api/v1/alerts

Get a paginated list of all your alerts with optional filtering and sorting.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 10, max: 100)
`status`	string	Filter by status: `active`, `paused`, `triggered`
`condition`	string	Filter by alert type (e.g., `price_above`, `price_below`)
`search`	string	Search by stock symbol or company name
`sort_field`	string	Sort field (default: `created_at`)
`sort_direction`	string	Sort direction: `asc`, `desc` (default: `desc`)

Example Request

curl -X GET "https://stockalert.pro/api/v1/alerts?status=active&limit=20" \
  -H "X-API-Key: sk_your_api_key"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "symbol": "AAPL",
      "condition": "price_above",
      "threshold": 200,
      "notification": "email",
      "status": "active",
      "created_at": "2024-01-05T10:00:00Z",
      "initial_price": 195.50,
      "parameters": null,
      "stocks": {
        "name": "Apple Inc.",
        "last_price": 195.50
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "total_pages": 3
    },
    "rate_limit": { "limit": 1000, "remaining": 999, "reset": 1736180400000 }
  }
}

Create Alert

POST/api/v1/alerts

Create a new stock alert with specified conditions.

Request Body

Field	Type	Required	Description
`symbol`	string	Yes	Stock ticker symbol (e.g., "AAPL")
`condition`	string	Yes	Type of alert (see Alert Types below)
`threshold`	number	Depends	Target value for the alert condition
`notification`	string	No	Channel: `email`, `sms` (default: `email`)
`parameters`	object	No	Additional parameters specific to alert type

Alert Types Reference

Alert Type	Description	Required Fields	Parameters
Price Alerts
`price_above`	Triggers when price rises above target	`symbol`, `threshold`	-
`price_below`	Triggers when price falls below target	`symbol`, `threshold`	-
`price_change_up`	Triggers on X% price increase	`symbol`, `threshold` (%)	-
`price_change_down`	Triggers on X% price decrease	`symbol`, `threshold` (%)	-
`new_high`	Triggers on new 52-week high	`symbol`	No `target_value` needed
`new_low`	Triggers on new 52-week low	`symbol`	No `target_value` needed
Technical Alerts
`ma_crossover_golden`	50-day MA crosses above 200-day MA	`symbol`	No `target_value` needed
`ma_crossover_death`	50-day MA crosses below 200-day MA	`symbol`	No `target_value` needed
`ma_touch_above`	Price touches MA from below	`symbol`, `threshold` (MA period in days)	e.g., 50 or 200
`ma_touch_below`	Price touches MA from above	`symbol`, `threshold` (MA period in days)	e.g., 50 or 200
`rsi_limit`	RSI crosses threshold	`symbol`, `threshold` (0-100)	`parameters.direction`: "above" or "below"
Volume Alerts
`volume_change`	Triggers when trading volume changes by X% vs average (20-day default; 100-day optional)	`symbol`, `threshold` (%)	`parameters.volumeBaseline`: `ma20` \| `ma100` (default `ma20`)
Fundamental Alerts
`pe_ratio_below`	P/E ratio falls below target	`symbol`, `threshold`	-
`pe_ratio_above`	P/E ratio rises above target	`symbol`, `threshold`	-
`forward_pe_below`	Forward P/E falls below target	`symbol`, `threshold`	-
`forward_pe_above`	Forward P/E rises above target	`symbol`, `threshold`	-
Time-based Alerts
`reminder`	One-time reminder	`symbol`	`parameters.date`: ISO date string
`daily_reminder`	Daily recurring reminder	`symbol`	`parameters.deliveryTime`: `market_open` (default) \| `after_market_close`
Dividend Alerts
`earnings_announcement`	Alert before earnings reports	`symbol`, `threshold` (days before)	e.g., 1–30
`dividend_ex_date`	Alert before ex-dividend date	`symbol`	No `target_value` needed
`dividend_payment`	Alert on dividend payment date	`symbol`	No `target_value` needed

Example Requests

Price Alert Example

curl -X POST https://stockalert.pro/api/v1/alerts \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "condition": "price_above",
    "threshold": 200,
    "notification": "email"
  }'

Volume Change Example

curl -X POST https://stockalert.pro/api/v1/alerts \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "TSLA",
    "condition": "volume_change",
    "threshold": 100,
    "notification": "email",
    "parameters": { "volumeBaseline": "ma20" }
  }'

Technical Alert Example (RSI)

curl -X POST https://stockalert.pro/api/v1/alerts \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "TSLA",
    "condition": "rsi_limit",
    "threshold": 70,
    "notification": "sms",
    "parameters": {
      "direction": "above"
    }
  }'

Moving Average Touch Example

curl -X POST https://stockalert.pro/api/v1/alerts \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "GOOGL",
    "condition": "ma_touch_above",
    "threshold": 200
  }'

Time-based Reminder Example

curl -X POST https://stockalert.pro/api/v1/alerts \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "NVDA",
    "condition": "reminder",
    "parameters": {
      "date": "2024-03-15T09:30:00Z"
    }
  }'

Daily Reminder (Market Close) Example

curl -X POST https://stockalert.pro/api/v1/alerts \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "condition": "daily_reminder",
    "parameters": {
      "deliveryTime": "after_market_close"
    }
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "symbol": "AAPL",
    "condition": "price_above",
    "threshold": 200,
    "notification": "email",
    "status": "active",
    "created_at": "2024-01-05T10:00:00Z",
    "initial_price": 195.50,
    "parameters": null
  },
  "meta": {
    "rate_limit": { "limit": 1000, "remaining": 999, "reset": 1736180400000 }
  }
}

Note: SMS notifications are only sent to your verified account phone number. You cannot specify custom phone numbers for security reasons.

Note about threshold: Some alert types (new_high, new_low, ma_crossover_golden, ma_crossover_death, daily_reminder) must NOT include a threshold. Including one will result in an error. Check the table above to see which alerts require threshold.

Get Alert

GET/api/v1/alerts/{id}

Get detailed information about a specific alert.

Path Parameters

id - The unique identifier of the alert

Example Request

curl -X GET https://stockalert.pro/api/v1/alerts/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: sk_your_api_key"

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "symbol": "AAPL",
    "condition": "price_above",
    "threshold": 200,
    "notification": "email",
    "status": "active",
    "created_at": "2024-01-05T10:00:00Z",
    "initial_price": 195.50,
    "parameters": null,
    "stocks": {
      "name": "Apple Inc.",
      "last_price": 213.55
    }
  },
  "meta": {
    "rate_limit": { "limit": 1000, "remaining": 999, "reset": 1736180400000 }
  }
}

Update Alert

PUT/api/v1/alerts/{id}

Update alert fields (condition, threshold, notification, parameters). Use dedicated endpoints to pause or activate an alert.

Request Body

Field	Type	Description
`condition`	string	Change the alert type (e.g., `price_above`, `rsi_limit`)
`threshold`	number\|null	Update threshold when required by the condition
`notification`	string	Notification channel: `email` or `sms`
`parameters`	object\|null	Additional parameters for certain conditions

Example Request

curl -X PUT https://stockalert.pro/api/v1/alerts/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "threshold": 210
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "threshold": 210
  },
  "meta": {
    "rate_limit": { "limit": 1000, "remaining": 999, "reset": 1736180400000 }
  }
}

Delete Alert

DELETE/api/v1/alerts/{id}

Permanently delete an alert. This action cannot be undone.

Example Request

curl -X DELETE https://stockalert.pro/api/v1/alerts/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: sk_your_api_key"

Example Response

{
  "success": true,
  "data": {
    "alertId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "deleted"
  },
  "meta": {
    "rate_limit": { "limit": 1000, "remaining": 999, "reset": 1736180400000 }
  }
}

Pause Alert

POST/api/v1/alerts/{id}/pause

Pause an active alert.

Example Request

curl -X POST https://stockalert.pro/api/v1/alerts/550e8400-e29b-41d4-a716-446655440000/pause \
  -H "X-API-Key: sk_your_api_key"

Activate Alert

POST/api/v1/alerts/{id}/activate

Reactivate a paused or triggered alert. Sets a new initial price.

Example Request

curl -X POST https://stockalert.pro/api/v1/alerts/550e8400-e29b-41d4-a716-446655440000/pause \
  -H "X-API-Key: sk_your_api_key"

Alert History

GET/api/v1/alerts/{id}/history

Fetch a paginated history of actions for an alert.

Example Request

curl -X GET "https://stockalert.pro/api/v1/alerts/550e8400-e29b-41d4-a716-446655440000/history?page=1&limit=20" \
  -H "X-API-Key: sk_your_api_key"

Log Alert History

POST/api/v1/alerts/history

Log an alert history event. Requires session or JWT authentication (no API key).

Request Body

{
  "alert_id": "a5d7e3f0-1234-4d8a-9c2b-111111111111",
  "symbol": "AAPL",
  "action_type": "paused",
  "previous_status": "active",
  "new_status": "paused",
  "alert_data": { "note": "Paused via API" },
  "trigger_price": null,
  "notification_status": null
}

Example Response

{
  "success": true,
  "data": { "success": true },
  "meta": {
    "rate_limit": { "limit": 1000, "remaining": 999, "reset": 1736180400000 }
  }
}

Verify Alert

POST/api/v1/alerts/verify

Verify an alert via token (guest allowed).

Example Request

curl -X POST https://stockalert.pro/api/v1/alerts/verify \
  -H "Content-Type: application/json" \
  -d '{
    "token": "verification_token_here"
  }'