API docs by Redocly

The Notifier SaaS API (v1)

Download OpenAPI specification:

Programmatic API for managing groups and group alerts.

API version: This document applies to API version v1. Pass Notifier-API-Version: v1 to override the account default per request. Successful responses echo the resolved version in the same response header.

Authentication

  1. Exchange your API key for an access token at POST /auth/token.
  2. Include Authorization: Bearer <access_token> on all protected routes.
  3. When the access token expires (15 minutes), call POST /auth/refresh with your refresh token and the expired access token.
  4. Refresh tokens expire after 30 days.

Rate limits

Token endpoints are limited per IP and API key prefix. Authenticated routes are limited per account session.

Validation

Path parameters such as groupId and alertId must be valid UUIDs. Invalid values return HTTP 400 with error.code of validation_error before any database lookup.

Invalid query parameter values return HTTP 400 with error.code of invalid_query_parameter. Invalid JSON request bodies and other request validation failures return HTTP 400 with error.code of validation_error.

Auth

API key exchange and token refresh

Exchange API key for tokens

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
optional
apiKey
string

Optional body field; Bearer header is preferred.

Responses

Request samples

Content type
application/json
{
  • "apiKey": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "tokenType": "Bearer",
  • "expiresIn": 0
}

Refresh access token

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
refreshToken
required
string

Responses

Request samples

Content type
application/json
{
  • "refreshToken": "string"
}

Response samples

Content type
application/json
{
  • "accessToken": "string",
  • "refreshToken": "string",
  • "tokenType": "Bearer",
  • "expiresIn": 0
}

Account

Account status and plan limits

Get account info

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "planName": "string",
  • "planLimits": {
    }
}

Groups

Group management

Create a group

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
name
required
string [ 1 .. 60 ] characters
memberLimit
integer or null >= 1
joinStartDate
string or null <date-time>
joinEndDate
string or null <date-time>
joinClosed
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "memberLimit": 1,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true
}

Response samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "status": "active",
  • "name": "string",
  • "memberLimit": 0,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true,
  • "joinLink": "string"
}

Update a group

Authorizations:
bearerAuth
header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
groupId
required
string <uuid>
name
string [ 1 .. 60 ] characters
memberLimit
integer or null >= 1
joinStartDate
string or null <date-time>
joinEndDate
string or null <date-time>
joinClosed
boolean
status
string
Enum: "active" "inactive"

Responses

Request samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "name": "string",
  • "memberLimit": 1,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true,
  • "status": "active"
}

Response samples

Content type
application/json
{
  • "groupId": "eb54e96e-21b8-4f54-9cd4-80fccbd06f55",
  • "status": "active",
  • "name": "string",
  • "memberLimit": 0,
  • "joinStartDate": "2019-08-24T14:15:22Z",
  • "joinEndDate": "2019-08-24T14:15:22Z",
  • "joinClosed": true,
  • "joinLink": "string"
}

List groups

Authorizations:
bearerAuth
query Parameters
status
string
Enum: "all" "active" "inactive"

Filter groups by status. Omit or set to all to return all groups. Set to active or inactive to filter. An empty value returns HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Get group statistics

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

query Parameters
timeframe
string
Default: "last12"
Enum: "last12" "current" "previous"

Time window for statistics. Defaults to last12 when omitted or empty. Invalid values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Alerts

Group alert scheduling and delivery

List group alerts

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

query Parameters
status
string
Enum: "all" "scheduled" "sent" "cancelled"

Filter alerts by status. Omit, leave empty, or set to all to return all alerts in the timeframe. Invalid values return HTTP 400.

timeframe
string
Default: "last12"
Enum: "last12" "current" "previous"

Time window for alerts. Defaults to last12 when omitted or empty. Invalid values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Schedule an alert

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
message
required
string [ 1 .. 80 ] characters
note
string or null <= 480 characters
link
string or null <= 2048 characters
sendAt
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "note": "string",
  • "link": "string",
  • "sendAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "alertId": "a9367074-b5c3-42c4-9be4-be129f43577e"
}

Get alert details

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

alertId
required
string <uuid>

Alert UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
{
  • "alertId": "a9367074-b5c3-42c4-9be4-be129f43577e",
  • "status": "scheduled",
  • "alert": {
    }
}

Update a scheduled alert

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

alertId
required
string <uuid>

Alert UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Request Body schema: application/json
required
message
string [ 1 .. 80 ] characters
note
string or null <= 480 characters
link
string or null <= 2048 characters
sendAt
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "message": "string",
  • "note": "string",
  • "link": "string",
  • "sendAt": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}

Cancel a scheduled alert

Authorizations:
bearerAuth
path Parameters
groupId
required
string <uuid>

Group UUID. Malformed values return HTTP 400.

alertId
required
string <uuid>

Alert UUID. Malformed values return HTTP 400.

header Parameters
Notifier-API-Version
string
Value: "v1"

Override the account default API version. Unsupported values return HTTP 400.

Responses

Response samples

Content type
application/json
Example
{
  • "error": {
    }
}