REST API

The REST API is allows you to integrate Alerts.boo into your apps & workflows. To start building with Alerts.boo, create an account at https://app.alerts.boo

Directory

You can also experiment with the code in our interactive Codepen Collection

We recommend using JSON Hero to view the sample objects

Command	API Route
Authentication	Visit on Web - https://app.alerts.boo/settings
Alert Payload	Sent to your webhook
Types Schema	Types reference for objects - Watcher, Log, User
Get Watcher	GET /watchers/:watcherID
List Watchers	POST /watchers/list
Create Watcher	POST /watchers/create
Update Watcher	POST /watchers/:watcherID/update
List Logs	POST /watchers/:watcherID/logs/list
Get Log	GET /logs/:logID
My Profile	GET /users/:userID
Rotate API Key	POST /users/:userID/rotate-token
Buy Credits	POST /billing/:userID/topup-credits

Get your API Key in the Settings Page

Be careful with your API Key! Anyone who has it can control your account. If your API key has been leaked, immediately rotate it.

Authentication

All commands in the REST API require authentication with an API Key. Copy your API Key from the web app settings page. Try the doc examples on your own data.

Get your API Key 👉 https://app.alerts.boo/settings

Be careful with your API Key! Anyone who has it can control your account. If your API key has been leaked, immediately rotate it.

Browser Screenshot (Find your API Key)

https://app.alerts.boo/settings

// Include your API key in every REST API command
// Put it in the headers { "api-key": "YOUR_API_KEY" } 
const API_KEY = 'YOUR_API_KEY'

fetch('https://api.alerts.boo/v1/ping', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY
  },
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Alert Payload

This is what gets sent to your webhook. Preview what is looks like so you can add it to your workflow or app.

Instagram

👉 View Sample Object

interface AlertPayload_Instagram {
  id: string // AlertID, for reference only
  logID: string // LogID, to lookup this exact payload
  watcherID: string // WatcherID, to know which watcher it came from
  createdAtUnix: number
  platform: string // "Instagram"
  type: string // "instagram_post" | "instagram_story"
  raw: any // the full original data from source
  url: string // the url to the content. eg instagram post
  data: {
    id: string // AlertID, for reference only
    slug: string // the shortcode or ID assigned by the source, eg. Instagram content ID
    author: string // the username of the account from source. eg. Instagram username
    url: string // the url to the content. eg instagram post
    caption: string // the caption of the post, or main text body
    location: string // any tagged location
    medias: SimpleMedia[] // a list of media content
    timestamp: string // ISO8601 datetime
  }
}
interface SimpleMedia {
  type: string // 'image' | 'video'
  url: string // link to the image or video url
  thumbnail: string // image thumbnail url
}

Twitter

Coming soon

Types Schema

Watcher

👉 View Sample Object

// Type Definition
interface Watcher {
  id: string // WatcherID
  platform: 'Instagram' // more coming soon
  alias: string // nickname you choose
  slug: string // eg. instagram username "insidehistory"
  url: string // link to the resource. eg. https://instagram.com/insidehistory
  createdAt: string // ISO8601 Date
  filterPrompt: string // Your Ai filter criteria
  status: string // 'Active' | 'Paused' | 'Awaiting' | 'Pending' | 'Insufficient Funds' | 'Problem'
  webhookUrl: string // your webhook to recieve alerts
  note: string // your private internal note
  autoExpireMs: number // pause watcher after inactivity
  expiresAt: string // ISO8601 Date
  userID: string // UserID
  customData?: {
    uid?: string // you can decide this
    data?: string // you can put whatever in here
  }
  lastReceivedAt?: string // ISO8601 Date
}

Log

👉 View Sample Object

// Type Definition
interface Log {
  id: string // LogID
  watcherID: string // WatcherID
  userID: string // UserID
  prompt: string // the Ai filter criteria that was used
  passPromptFilter: boolean // did it pass Ai filter criteria
  status: string // 'Finished' | 'Skipped' | 'Pending'
  platform: string // 'Instagram' | 'Twitter'
  type: string // 'instagram_story' | 'instagram_post'
  alias: string // quick title to summarize
  memo: string // text details
  createdAt: string // ISO8601 Date
  url: string // link to the post on Instagram, etc
  fullObjectUrl: string // link to the full Instagram post data
  creditsConsumed: number // cost of log
}

User

👉 View Sample Object

// Type Definition
interface User {
  id: string // UserID
  alias: string // nickname
  email: string // email used to register
  apiToken: string // api key, keep this private
  createdAt: string // ISO8601 Date
  walletCreditBalance: number // credits in your wallet
  billingPlanLabel: string // your pricing plan
  paymentCard?: {
    last4: string // last 4 numbers of your credit card on file
  }
}

Get Watcher

GET /watchers/:watcherID View a Watcher in detail, excluding its logs. If you want logs, use List Logs.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const WATCHER_ID = 'YOUR_WATCHER_ID'

fetch(`https://api.alerts.boo/v1/watchers/${WATCHER_ID}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY
  },
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  watcher: Watcher // Scroll up for Type Schema
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

---

List Watchers

POST /watchers/list List all the watchers owned by you. Filter by attributes and paginate through results. Can also be used to search by exact username.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const query = {
  status: "Active",
  platform: "Instagram",
  limit: 5,
  // slug: "instagramusername",
  // cursor: "id-of-prev-last-watcher",
  // customDataUID: "your-custom-lookup-id"
}

fetch(`https://api.alerts.boo/v1/watchers/list`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY
  },
  body: JSON.stringify(query)
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  watchers: Watcher[], // Scroll up for Type Schema
  nextCursor: string, // WatcherID
  count: number
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

Argument	Type	Description
status	enum	Optional. Filter by watcher status. Options are Active , Awaiting, Pending, Paused, Problem, Insufficient Funds . Leave blank for all.
platform	enum	Optional. Filter by platform. Options are Instagram or Twitter
slug	string	Optional. Search by exact username match, case insensitive.
limit	number	Optional. Limit the search results. Default is 20, max is 100
cursor	WatcherID	Optional Pagination. The string ID of the last Watcher of your previous query.
customDataUID	string	Optional. A string field indexed for you to use as a custom searchable ID (eg. your users). Max 256 chars.

---

Create Watcher

POST /watchers/create Create a new Watcher with advanced features such as custom metadata & auto-expire after inactivity.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const payload = {
    url: "https://instagram.com/insidehistory",
    webhookUrl: "https://yourapp.com/your-webhook",
    filterPrompt: "Alert me if its a post about the Roman Empire",
    note: "A private note for your team",
    alias: "A friendly title for your team",
    autoExpireMs: 1000*60*60*24*30, // auto-pause after 30 days inactivity
    customData: {
        uid: "your-custom-unique-id",
        data: JSON.stringify({ hello: 'world' })
    }
}

fetch(`https://api.alerts.boo/v1/watchers/create`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  watcher: Watcher, // Scroll up for Type Schema
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

Argument	Type	Description
url	string	Required. The url of your watchers source. For example, a pages' Instagram profile URL.
webhookUrl	string	Optional. The url of your webhook that will recieve alerts. Use empty string to remove webhook.
filterPrompt	string	Optional. The prompt for the Ai use as filter criteria. Determines if you get alerted. Max 2000 chars. Use empty string to remove filter criteria.
alias	string	Optional. A human friendly name to identify your watcher. Max 256 chars.
autoExpireMs	number	Optional. Watchers can auto-expire if it hasn't seen any activity in milliseconds. Defaults to 3 months. Min 1 hour, Max 10 years.
note	string	Optional. A private note only you can see. Max 10k chars.
customData.uid	string	Optional. A string field indexed for you to use as a custom searchable ID (eg. your users). Max 256 chars.
customData.data	string	Optional. A string serialized object for any additional data you want to store. Max 100kb or 100k chars.

---

---

Update Watcher

POST /watchers/:watcherID/update Update a Watcher with advanced features such as custom metadata & auto-expire after inactivity.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const WATCHER_ID = 'WATCHER_ID'
const payload = {
  status: "Paused",
  webhookUrl: "https://yourapp.com/other-webhook",
  filterPrompt: "Alert me if its a post about collapse of the Roman Empire",
  note: "Still a private note",
  alias: "A friendly title for your team",
  autoExpireMs: 1000*60*60*24*30, // auto-pause after 30 days inactivity
  customData: {
    uid: "your-custom-unique-id",
    data: JSON.stringify({ hello: 'world' })
  }
}

fetch(`https://api.alerts.boo/v1/watchers/${WATCHER_ID}/update`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  trigger: Trigger, // Scroll up for Type Schema
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

Argument	Type	Description
status	enum	Optional. Set watcher status to Active or Paused or Inactive (Be careful with Inactive as it is equal to a deletion and cannot be undone).
webhookUrl	string	Optional. The url of your webhook that will recieve alerts. Use empty string to remove webhook.
filterPrompt	string	Optional. The prompt for the Ai use as filter criteria. Determines if you get alerted. Max 2000 chars. Use empty string to remove filter criteria.
note	string	Optional. A private note only you can see. Max 10k chars.
alias	string	Optional. A human friendly name to identify your watcher. Max 256 chars.
autoExpireMs	number	Optional. Watchers can auto-expire if it hasn't seen any activity in milliseconds. Defaults to 3 months. Min 1 hour, Max 10 years.
customData.uid	string	Optional. A string field indexed for you to use as a custom searchable ID (eg. your users). Max 256 chars.
customData.data	string	Optional. A string serialized object for any additional data you want to store. Max 100kb or 100k chars.

---

List Logs

POST /watchers/:watcherID/logs/list List the most recents logs from a Watcher. Paginate through logs by most recent first.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const WATCHER_ID = 'WATCHER_ID'
const query = {
  limit: 50, // always returned newest first
  cursor: 'prev-watcher-id'
}

fetch(`https://api.alerts.boo/v1/watchers/${WATCHER_ID}/logs/list`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY 
  }
  body: JSON.stringify(query)
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  logs: Log[], // Scroll up for Type Schema
  nextCursor: string, // LogID
  count: number
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

Argument	Type	Description
limit	number	Optional. Limit the search results. Default is 20, max is 100
cursor	LogID	Optional Pagination. The string ID of the last Log of your previous query.

---

Get Log

GET /logs/:logID Get details of a specific log.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const logID = "YOUR_LOG_ID"

fetch(`https://api.alerts.boo/v1/logs/${logID}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY 
  }
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  log: Log, // Scroll up for Type Schema
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

---

My Profile

GET /users/:userID Get user details of your account.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const userID = "YOUR_USER_ID"

fetch(`https://api.alerts.boo/v1/users/${userID}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY 
  }
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  user: User, // Scroll up for Type Schema
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

---

Rotate API Key

POST /users/:userID/rotate-token Rotate your accounts' API key and return the new key in response. Be careful as old keys will stop working.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const userID = "YOUR_USER_ID"

fetch(`https://api.alerts.boo/v1/users/${userID}/rotate-token`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY
  }
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));Request

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  user: User, // Scroll up for Type Schema
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

---

Buy Credits

POST /billing/:userID/topup-credits Buy additional credits to pay for your usage. You will first need to setup billing by entering your credit card in the webapp settings page 👉 https://app.alerts.boo/settings Use this API route to programmatically buy more credits whenever you need. Your default credit card will be billed.

Request

// copy paste this to your browser console to run
const API_KEY = 'YOUR_API_KEY'
const userID = "YOUR_USER_ID"
const payload = {
  amount: 1000
}
 
fetch(`https://api.alerts.boo/v1/billing/${userID}/topup-credits`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'api-key': API_KEY
  },
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => console.log(data));
  .catch(error => console.log(error));

Response

👉 View Sample Response

// Type Definition
interface ResponseBody {
  txID: string, // purchase reciept ID
  creditsReceived: number,
  pricePaid: number, // in USD eg. 5.00 = five dollars usd
  currency: "USD", // always the same USD
  cardCharged: string // last 4 digits of credit card on file
}

Try It

Click "Run Pen" and "JS" button for the interactive code Recommended to open in new tab (click Edit on Codepen)

Argument	Type	Description
amount	number	Required. The amount of credits you would like to buy as a one-time purchase. Min 20 credits, Max 40k credits.

---

Rate Limits

There are 3 rate limits for the REST API. Contact us if you need more.

Rate	Routes
1 per 3 seconds	POST /billing/:userID/topup-credits POST /users/:userID/rotate-token
3 per 3 seconds	POST /watchers/list POST /watchers/:watcherID/logs/list
10 per 3 seconds	Everything Else