API Documentation

Integrate alert.new into your applications

By using the API, you agree to our Terms of Service, Privacy Policy, and Acceptable Use Policy.

Base URL

https://alert.new/api/v1

URL Structure

alert.new uses pretty URLs based on the target URL:

Feed page: alert.new/github.com/facebook/react

RSS feed: alert.new/github.com/facebook/react.rss

JSON feed: alert.new/github.com/facebook/react.json

Atom feed: alert.new/github.com/facebook/react.atom

User-specific feeds with filters:

User RSS: alert.new/@alice/github.com/facebook/react.rss?token=rt_xxx

User OPML: alert.new/@alice.opml?token=rt_xxx

Authentication

API requests require an API key passed in the Authorization header:

Authorization: Bearer sk_live_your_api_key

API keys are available for Pro and Team users. Generate keys in your dashboard.

Token Types

sk_live_* — API key for full access
rt_* — RSS token for read-only feed access (safe to embed in URLs)

Feed Endpoints

GET/feeds

List public feeds with pagination

Response

{
  "feeds": [
    {
      "id": "abc123",
      "url": "https://github.com/facebook/react",
      "title": "facebook/react",
      "logo": "https://github.com/facebook.png",
      "subscriberCount": 42,
      "lastChangedAt": "2024-01-15T12:00:00Z",
      "rssUrl": "https://alert.new/github.com/facebook/react.rss"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "hasMore": true
  }
}

POST/feeds

Create a new feed for a URL. The title is automatically generated from the URL (e.g., owner/repo for GitHub, r/subreddit for Reddit).

Request Body

{
  "url": "https://github.com/facebook/react"
}

Response

{
  "id": "abc123",
  "url": "https://github.com/facebook/react",
  "title": "facebook/react",
  "logo": "https://github.com/facebook.png",
  "subscriberCount": 0,
  "createdAt": "2024-01-15T00:00:00Z",
  "rssUrl": "https://alert.new/github.com/facebook/react.rss"
}

GET/feeds/:id

Get feed details and current data

Response

{
  "id": "abc123",
  "url": "https://github.com/facebook/react",
  "title": "facebook/react",
  "logo": "https://github.com/facebook.png",
  "data": {
    "stars": 220000,
    "forks": 45000,
    "version": "18.2.0"
  },
  "subscriberCount": 42,
  "lastCheckedAt": "2024-01-15T12:00:00Z",
  "rssUrl": "https://alert.new/github.com/facebook/react.rss"
}

GET/feeds/:id/changes

Get recent changes for a feed

Response

{
  "changes": [
    {
      "id": "chg123",
      "field": "stars",
      "oldValue": "219500",
      "newValue": "220000",
      "detectedAt": "2024-01-15T12:00:00Z"
    }
  ]
}

POST/feeds/:id/check

Trigger an immediate check for a feed (Pro only)

Response

{
  "success": true,
  "data": {
    "stars": 220000,
    "forks": 45000
  },
  "changes": [],
  "checkedAt": "2024-01-15T12:00:00Z"
}

Subscription Endpoints

GET/subscriptions

List your subscriptions

Response

{
  "subscriptions": [
    {
      "id": "sub123",
      "feedUrl": "github.com/facebook/react",
      "feedTitle": "facebook/react",
      "every": "1h",
      "when": ["stars>200000"],
      "watch": ["stars", "version"],
      "ignore": [],
      "notifications": {
        "email": true,
        "webhook": "https://myapp.com/alerts"
      },
      "private": false,
      "createdAt": "2024-01-15T00:00:00Z",
      "rssUrl": "https://alert.new/@alice/github.com/facebook/react.rss?token=rt_xxx"
    }
  ]
}

POST/subscriptions

Create a new subscription. Subscriptions save your personal filter and notification settings for a feed.

Request Body

{
  "url": "github.com/facebook/react",
  "every": "1h",
  "when": ["stars>200000"],
  "watch": ["stars", "version"],
  "notifications": {
    "email": true,
    "webhook": "https://myapp.com/alerts"
  },
  "private": false
}

Response

{
  "id": "sub123",
  "feedUrl": "github.com/facebook/react",
  "feedTitle": "facebook/react",
  "every": "1h",
  "when": ["stars>200000"],
  "watch": ["stars", "version"],
  "ignore": [],
  "notifications": {
    "email": true,
    "webhook": "https://myapp.com/alerts"
  },
  "private": false,
  "createdAt": "2024-01-15T00:00:00Z",
  "rssUrl": "https://alert.new/@alice/github.com/facebook/react.rss?token=rt_xxx",
  "links": {
    "self": "https://alert.new/api/v1/subscriptions/sub123",
    "feed": "https://alert.new/github.com/facebook/react",
    "feedJson": "https://alert.new/github.com/facebook/react.json"
  }
}

PATCH/subscriptions/:id

Update subscription settings

Request Body

{
  "every": "15m",
  "when": ["stars>250000"]
}

Response

{
  "id": "sub123",
  "feedUrl": "github.com/facebook/react",
  "every": "15m",
  "when": ["stars>250000"],
  ...
}

DELETE/subscriptions/:id

Delete a subscription

Response

{
  "success": true
}

View Filters (Query Parameters)

Apply temporary filters to feed views without creating a subscription:

Parameter	Example	Description
every	5m, 1h, 1d	Frequency filter
when	price<100	Condition filter
watch	price,stock	Only show these fields
ignore	comments	Hide these fields
since	2024-01-01	Changes after date
limit	10	Max changes

alert.new/github.com/facebook/react.json?watch=stars,latestRelease

Recipes Endpoints

Recipes are open-source extraction templates that understand specific websites. These endpoints are public and don't require authentication.

GET/recipes

List all available recipes with their metadata, fields, and default alerts

Response

{
  "recipes": [
    {
      "slug": "github",
      "name": "GitHub Repository",
      "description": "Track stars, releases, and activity",
      "icon": "https://github.githubassets.com/favicons/favicon.svg",
      "category": "developer",
      "fields": [
        { "key": "stars", "label": "Stars", "type": "number", "primary": true }
      ],
      "defaultAlerts": [
        { "id": "new-release", "label": "New Release", "when": "version != previous.version" }
      ]
    }
  ],
  "count": 9
}

GET/recipes/:slug

Get details for a specific recipe

Response

{
  "slug": "amazon",
  "name": "Amazon Product",
  "description": "Track prices and availability",
  "icon": "https://www.amazon.com/favicon.ico",
  "category": "ecommerce",
  "fields": [...],
  "defaultAlerts": [...]
}

Rate Limits

Rate limits are applied per IP address to prevent abuse while remaining generous for legitimate use.

Endpoint	Limit	Auth
Public endpoints (/api/search, /recipes)	120/min	None
API endpoints (/feeds, /subscriptions)	60/min	API Key
Form submissions (subscribe)	30/min	Turnstile
Team tier	300/min	API Key

Webhooks

Pro users can configure webhooks to receive real-time notifications when feeds change. Webhooks are sent as HTTP POST requests with a JSON payload.

Payload Example

{
  "event": "feed.changed",
  "feed": {
    "id": "abc123",
    "url": "https://github.com/facebook/react",
    "title": "facebook/react"
  },
  "changes": [
    {
      "field": "latestRelease",
      "oldValue": "v18.2.0",
      "newValue": "v18.3.0"
    }
  ],
  "timestamp": "2024-01-01T12:00:00Z"
}

Headers

Content-Type: application/json

User-Agent: AlertNew-Webhook/1.0

X-AlertNew-Event: feed.changed

X-AlertNew-Delivery: unique-delivery-id

X-AlertNew-Timestamp: 2024-01-01T12:00:00Z

X-AlertNew-Signature: sha256=...

Verifying Signatures

If you provide a webhook secret, we sign the payload using HMAC-SHA256. Verify by computing HMAC-SHA256(secret, body) and comparing to the signature header.

RSS Feeds

Every feed has a free RSS endpoint that you can subscribe to with any RSS reader.

Public Feed URL

https://alert.new/{target_url}.rss

User Feed URL (with filters)

https://alert.new/@{username}/{target_url}.rss?token=rt_xxx

Examples

curl https://alert.new/github.com/facebook/react.rss

curl "https://alert.new/github.com/facebook/react.json?limit=5"

curl https://alert.new/@alice/github.com/facebook/react.rss?token=rt_xxx

Slack & Discord Integration

Pro users can also send notifications directly to Slack or Discord channels.

Slack

Configure an incoming webhook URL from Slack and we'll post formatted messages with change details.

Discord

Add your Discord webhook URL and receive rich embed notifications with color-coded changes.