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/public/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
`sortField`	string	Sort field (default: `created_at`)
`sortDirection`	string	Sort direction: `asc`, `desc` (default: `desc`)

Example Request

curl -X GET "https://stockalert.pro/api/public/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
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45,
    "totalPages": 3
  }
}

Create Alert

POST/api/public/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`	`parameters.period`: 50 or 200
`ma_touch_below`	Price touches MA from above	`symbol`	`parameters.period`: 50 or 200
`rsi_limit`	RSI crosses threshold	`symbol`, `threshold` (0-100)	`parameters.direction`: "above" or "below"
Volume Alerts
`volume_change`	Volume spike above average	`symbol`, `threshold` (%)	-
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`	No `target_value` needed
Dividend Alerts
`earnings_announcement`	Alert before earnings reports	`symbol`	No `target_value` needed
`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/public/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"
  }'

Technical Alert Example (RSI)

curl -X POST https://stockalert.pro/api/public/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/public/v1/alerts \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "GOOGL",
    "condition": "ma_touch_above",
    "parameters": {
      "period": 200
    }
  }'

Time-based Reminder Example

curl -X POST https://stockalert.pro/api/public/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"
    }
  }'

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
  }
}

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/public/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/public/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
    }
  }
}

Update Alert

PUT/api/public/v1/alerts/{id}

Activate or pause an existing alert.

Request Body

Field	Type	Description
`status`	string	Set to `"paused"` to pause, `"active"` to reactivate

Example Request

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

Example Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "paused"
    // ... full alert object returned
  }
}

Delete Alert

DELETE/api/public/v1/alerts/{id}

Permanently delete an alert. This action cannot be undone.

Example Request

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

Example Response

{
  "success": true,
  "message": "Alert deleted successfully"
}