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

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.

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
}

Types Schema

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

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

// 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.

// 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));

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

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.

// 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));

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

Create Watcher

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

// 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));

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

Update Watcher

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

// 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));

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

List Logs

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

// 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));

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

Get Log

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

// 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));

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

My Profile

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

// 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));

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

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.

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

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

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.

// 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));

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

Rate Limits

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

PreviousGetting Started

Last updated 8 months ago

REST API

Directory

Authentication

Alert Payload

Types Schema

Get Watcher

List Watchers

Create Watcher

Update Watcher

List Logs

Get Log

My Profile

Rotate API Key

Buy Credits

Rate Limits

Directory

Authentication

Alert Payload

Types Schema

Get Watcher

List Watchers

Create Watcher

Update Watcher

List Logs

Get Log

My Profile

Rotate API Key

Buy Credits

Rate Limits