Alertmouse API - Cheesy Docs

Alertmouse tracks brands, products and competitors on the internet. Our API gives you direct access to the same alerts and mentions that power our product, so you can build custom workflows on top of Alertmouse.

Heads up! The API is only available to enterprise customers.

The API and docs were designed for both humans and LLMs. Have fun!

Getting Started

Create an API key on your Settings Page. Anyone with your team's API key can read your alerts and mentions, so keep it secret. Your super-secret API key will look like this:

sk-xxxxxxxxxxxxxxxxxxxxx

Each request must include an Authorization: Bearer <api key> header with your team's API key. The GET /api/hello request is a good place to start. Once that works you are ready to make some real requests.

GET /api/hello

A helpful ‘Hello, world!’ API to get you started

# don't forget to fill in your actual API key!
curl --get https://alertmouse.com/api/hello \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  data: {
    version: "1.0",
  },
}

Alerts

An alert is a tracking rule that tells Alertmouse what phrase to watch for. Our army of mice searches tirelessly for your phrase and emails you each mention we discover. Alerts look like this:

alert data model
id	string	unique alert_id, like `a-9IvoHbyl`
phrase	string	the main search phrase
must_include_one	string[]	(optional) only return mentions that include one of these keywords
cannot_include_any	string[]	(optional) exclude mentions with these keywords

The must_include_one and cannot_include_any properties are advanced filters for use with tricky phrases that return too many irrelevant mentions. These filters are powerful, so use with caution to avoid missing out on important mentions!

Mentions

A mention is a single result from one of your alerts. Important note about dates - sometimes Alertmouse discovers mentions that are sadly quite ancient. Old mentions can turn up at any time. The date field shows when Alertmouse discovered the mention as part of our diligent work. Take note of content_date, which indicates if we found another (possibly old) date in the mention's content.

mention data model
id	string	unique mention_id, such as `m-UOv8qvJx`
alert_id	string	the alert that contains this mention
link	string	source URL for the mention
date	date	when we discovered the mention
score	integer	our score for the mention `1-100`
content	json	a JSON blob for title/snippet/etc
content.title	string	title from the page or content
content.snippet	string (optional)	short excerpt or preview
content.content_date	date (optional)	date found in the content

API Reference

GET /api/alerts

Get list of alerts for this team. The only query parameters are for pagination.

curl --get https://alertmouse.com/api/alerts \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  data: [
    { id: "a-9IvoHbyl", phrase: "Rand Fishkin" },
    { id: "a-GhYSgPYp", phrase: "ultrasonics" },
    // ...
  ],
  meta: {}, // see pagination
}

GET /api/alerts/{alert_id}

Get one alert.

curl --get https://alertmouse.com/api/alerts/a-9IvoHbyl \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  data: {
    id: "a-9IvoHbyl",
    phrase: "Rand Fishkin",
    must_include_one: ["marketing", "seo", "author"],
    cannot_include_any: ["bros"],
  },
}

POST /api/alerts

Create a new alert. Shortly after a new alert is created, we will begin looking for recent mentions from the last 30 days. This can take a few minutes, so be patient.

curl https://alertmouse.com/api/alerts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrase": "Rand Fishkin"
  }'

{
  data: {
    id: "a-9IvoHbyl",
    phrase: "Rand Fishkin",
  },
}

If you're getting too many irrelevant mentions, you can create an alert with advanced filters. Here's an example:

curl https://alertmouse.com/api/alerts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrase": "Rand Fishkin",
    "must_include_one": ["marketing", "seo", "author"],
    "cannot_include_any": ["bros"]
  }'

{
  data: {
    id: "a-9IvoHbyl",
    phrase: "Rand Fishkin",
    must_include_one: ["marketing", "seo", "author"],
    cannot_include_any: ["bros"],
  },
}

PATCH /api/alerts/{alert_id}

Update an existing alert. This will DELETE all the existing mentions for the alert. They will be replaced with recent mentions from the last 30 days for the updated alert. This can take a few minutes, so be patient.

curl -X PATCH https://alertmouse.com/api/alerts/a-9IvoHbyl \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phrase": "Geraldine DeRuiter"
  }'

{
  data: {
    id: "a-9IvoHbyl",
    phrase: "Geraldine DeRuiter",
  },
}

This endpoint supports partial updates. Only pass the fields you want to change. All other fields will remain unchanged. If you want to clear out an array field, pass an empty array [].

DELETE /api/alerts/{alert_id}

Delete an existing alert and all its mentions. Beware! This cannot be reversed and you will not be able to recover your old mentions.

curl -X DELETE https://alertmouse.com/api/alerts/a-9IvoHbyl \
  -H "Authorization: Bearer YOUR_API_KEY"

HTTP 204 No Content

GET /api/alerts/{alert_id}/mentions

Get list of mentions for this alert, sorted by date. Supports pagination.

query parameters
since	date or mention_id (optional)	Only return mentions discovered after a certain timestamp (`2026-04-01T04:00:00-07:00`). Or specify a mention_id (`m-kGUGew1M`) to get a list of mentions discovered after that one. Handy for cron jobs.

curl --get https://alertmouse.com/api/alerts/a-9IvoHbyl/mentions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "page=2" \
  -d "since=2026-04-01T04:00:00-07:00"

{
  data: [
    {
      id: "m-UOv8qvJx",
      link: "https://example.com/hi",
      // ... score, content, etc.
    },
    {
      id: "m-Z5l86IAv",
      link: "https://altavista.com/tips",
      // ... score, content, etc.
    },
    // ...
  ],
  meta: {}, // see pagination
}

GET /api/mentions/{mention_id}

Get one mention.

curl https://alertmouse.com/api/mentions/m-UOv8qvJx \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  data: {
    id: "m-UOv8qvJx",
    link: "https://example.com/hi",
    date: "2026-04-22T18:30:00Z",
    score: 87,
    alert_id: "a-9IvoHbyl",
    content: {
      title: "OpenAI ships a new release",
      snippet: "API improvements.",
      content_date: "2025-02-12",
    },
  },
}

Pagination

Some API requests support pagination. Use these (optional) query parameters to move through a list of items:

pagination query parameters
page	page number to fetch, between `1-10`
per_page	number of items per page, between `20-100` (default 20)

Requests that support pagination always return a special meta section as part of the response. The meta section shows which page you are on and how much further you can go:

pagination meta response
page	integer	current page
per_page	integer	how many items per page
total_items	integer	how many items available to fetch
total_pages	integer	how many pages available to fetch
has_more	boolean	true if there are more pages

Here is a complete example:

curl --get https://alertmouse.com/api/alerts/a-GhYSgPYp/mentions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d "page=3" \
  -d "per_page=100"

{
  data: {
    // ...
  },
  meta: {
    page: 3,
    per_page: 100,
    total_items: 487,
    total_pages: 5,
    has_more: true,
  },
}

Rate Limits

The Alertmouse API allows up to 60 requests per minute for each team. If you exceed the limit, the API returns 429 Too Many Requests. Each 429 includes a Retry-After: header so your client knows when to try again.

Errors

When a request fails, we return a non-200 error status and an error string:

{
  error: "stinky cheese",
}