Skip to content

StatusHub Public API (3.0-R1)

The StatusHub Public API v3

StatusHub API V3 is a REST API with JSON as a content type for both request body and responses.

Work in progress

Current version of API V3 is still a work in progress. Certain features or endpoints are still missing.
The goal is to provide the API that will allow exactly the same actions as StatusHub Control Panel.

StatusHub regions and API URL

All API requests should be made on hostname used to sign-in into StatusHub Control Panel.
For example if team members sign into account on:
https://company.app.statushub.io
then API requests should be made with following prefix:
https://company.app.statushub.io/api/v3

EU region

Same rule follows for customers using EU region and then the example would be:
If team members sign into account on:
https://company.app-eu1.statushub.io
then API requests should be made with following prefix:
https://company.app-eu1.statushub.io/api/v3

Rate limiting

StatusHub API has two rate limits:

  • GET requests - 30 requests per second
  • All other requests - 5 requests per second

Rate limit is bounded to API Key used for authentication.
When rate limit will be exceeded, StatusHub API will respond with:

  • 429 response code
  • {"error":"Too many requests - please retry later"} response
  • Retry-After response header

In special cases certain API method may have different rate limit which will be mentioned in API method description.

Time zones

All date/time parameters should be passed in UTC zone no matter the default zone Hub settings.

Filtering events by time range

Events like Incident or Maintenance events can be filtered by time range.
There are two optional parameters in INDEX endpoints:

  • start_time,
  • end_time.

Filtering logic is returning those events which period of occurrence overlaps with start_time and end_time range.
Also, providing just one of range params, still uses the range but with a default value of not provided one:

  • Providing just start_time assumes end_time as far in the future,
  • Providing just end_time assumes start_time as far in the past.
  • Not providing start_time nor end_time results in start_time being far in the past and end_time being far in the future and as a result all events are returned by time range filter.

Below are few examples to better understand the logic:

Maintenance example

Let's assume maintenance that started on 2025-02-01 and finished on 2025-02-08.

Using start_time=2025-01-01T00:00:00Z and end_time=2025-02-02T00:00:00Z will return the event because there is an overlap of both ranges:
<2025-01-01 00:00:00 UTC, 2025-02-02 00:00:00 UTC> and
<2025-02-01 00:00:00 UTC, 2025-02-08 00:00:00 UTC> overlap in
<2025-02-01 00:00:00 UTC, 2025-02-02 00:00:00 UTC>.

Open incident example

Let's assume incident that started on 2025-02-01 and hasn't been resolved.

Using start_time=2025-03-01T00:00:00Z and not provind end time will return the event because there is an overlap of both ranges:
<2025-01-01 00:00:00 UTC, far in future due to incident still being open> and
<2025-03-01 00:00:00 UTC, far in future due to not providing end_time> overlap in
<2025-03-01 00:00:00 UTC, far in future>.

Extended properties

StatusHub API V3 supports extended versions of certain response properties. By default less frequently required fields are returned in basic form with most common properties but if more information is needed extend query parameter can be used.
Currently StatusHub API V3 supports extending:

  • Incident flags,
  • Incident Update flags,
  • Maintenance event flags,
  • Subscription flags.

    Example for Maintenance flags:
  • Request path with basic flags: /api/v3/hubs/hub-subdomain/maintenances,
  • Request path with extended flags: /api/v3/hubs/hub-subdomain/maintenances?extend=flags
Download OpenAPI description
api-v3-openapi.json
api-v3-openapi.yaml
Overview
URL

https://statushub.com/contact/

StatusHub Support

support@statushub.dev

Terms of Service

Languages
Servers
Main US region

https://{accountSubdomain}.app.statushub.io/api/v3/

EU region

https://{accountSubdomain}.app-eu1.statushub.io/api/v3/

Incident

Incident is a most important event type.
Incident represents an event that:

  • Started in the past,
  • Have updates which can be added while incident is being handled,
  • During creation and during its duration the total duration or end of the incident is not known,
  • Is resolved when resolved Incident Update is created for this incident,
  • Have non-0 duration. This means that Incident can't be created with resolved incident type.

Most typical use case:

  • Hub page list various customer-facing services,
  • When one of the services has an outage, Incident is created manually or through automation,
  • While team is working on restoring the service Incident Update entries are added manually or through automation to this incident to let customers know what's happening,
  • Once issue is resolved, Incident Update with monitoring incident type is being created while team is keeping an eye on service health,
  • Once situation is stable, Incident Update with resolved incident type is being created which ends the Incident.
Operations

Incident Update

Incident Update represents single update for Incident.
Every Incident consts of at least one Incident Update and a resolved incident consists of at least two Incident Updates where the second one has resolved incident type.

Operations

Maintenance

Maintenance represents an event that:

  • Has known start time which is typically in future - planned maintenance,
  • Has known end time during the moment of creation,
  • Is a single message.

Most typical use case:

  • Hub page list various custom-facing services,
  • One of the service will undergo a maintenance that will take it offline for duration of the maintenance,
  • Ahead of time, Maintenance event is created to let customers know that service will not be available during specific time-frame.
Operations

Incident Update Template

Incident Update Template is used to create Incident Updates in StatusHub Control Panel quicker.
It can contain predefined:

  • title,
  • body,
  • incident type,
  • service statuses.
Operations

Maintenance Template

Maintenance Template is used to create Maintenance event in StatusHub Control Panel quicker.
It can contain predefined:

  • title,
  • body,
  • duration,
  • service statuses.
Operations

Platform Alert

Platform Alert is a state of Hub which typically represent major event affecting whole product as opposed to Incident or Maintenance which affects specific services.
Platform Alert is not connected with any service and therefore notification about Platform Alert are sent to all subscriptions regardless of their service selection.

Operations

Hub

Hub is a central record that represents the status page and holds all related records.

Operations

Hub Privacy

Operations

Assets

Asset is a generic record that typically represents binary data like image that can be referenced and used in other records.
For example a Hub logo or favicon.

Operations

Group

Group purpose is to group Services in logical groups.

Operations

Service

Service represents fundamental Hub entity. Incident and Maintenance events are always attached to at least one Service. Service status should represent the health of the actual real-life entity it represents.

Operations

Connected Group

Connected Group is a special representation of actual Group that through its Services is attached to Connected Hub.

Operations

Connected Service

Connected Service is a special representation of actual Service that is attached to Connected Hub.

Operations

Subscriber

Subscriber represents a consumer of StatusHub notifications that can have multiple subscriptions.

Operations

Create a Subscriber

Request

Creates a new Subscriber.
Main purpose of Subscriber is to create a record to which later one or many subscriptions can be added. One Subscriber can have multiple methods of communication associated with it.
It also allows to set SAML NameID that can be then used to recognize Subscriber after sign-in into protected Hub Page.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

Query
api_versionstring

Api version

Value"V3-R1"
Bodyapplication/json
idp_idstring or null

Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.

Example: "internal-identifier-at-company.com"
subscriptionsArray of objectsnon-emptyrequired
subscriptions[].​addressstringrequired

Address for a subscription. Exact meaning depends on method name:

  • email - email address,
  • sms - phone number,
  • webhook - URL,
  • slack - Slack Incoming Webhook URL,
  • teams - MS Teams Incoming Webhook URL.
Example: "example@statushub.com"
subscriptions[].​method_namestringrequired
Enum"email""sms""webhook""slack""teams"
Example: "email"
subscriptions[].​services_selectionobjectrequired

"all" has precedence over "services". If "all" is false, "services" can't be empty. If "all" is true, "services" value is being ignored

subscriptions[].​services_selection.​allbooleanrequired

true it means that Subscription is subscribed to all current and future Services in current Hub.
When false, service_ids can not be empty.

Example: false
subscriptions[].​services_selection.​service_idsArray of integers

StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies all to be true so subscribing to all current and future Services for current Hub.

Example: [449,24221,2]
subscriptions[].​configurationobject

Additional configuration for this method name or this Subscription

Example: {"content_type":"application/json"}
subscriptions[].​labelstring or null

Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.

Example: "Responsible person name"
subscriptions[].​less_verboseboolean

Subscription will receive the minimum number of notifications per incident - typically first and final.

Default false
Example: true
subscriptions[].​protectedboolean

Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.

Default false
Example: false
subscriptions[].​subscriber_idinteger

id of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.

curl -i -X POST \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/subscribers?api_version=V3-R1' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "idp_id": "internal-identifier-at-company.com",
    "subscriptions": [
      {
        "address": "example@statushub.com",
        "method_name": "email",
        "services_selection": {
          "all": false,
          "service_ids": [
            449,
            24221,
            2
          ]
        },
        "configuration": {
          "content_type": "application/json"
        },
        "label": "Responsible person name",
        "less_verbose": true,
        "protected": false,
        "subscriber_id": 0
      }
    ]
  }'

Responses

OK

Bodyapplication/json
idinteger>= 1
Example: 63
idp_idstring or null

Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.

Example: "internal-identifier-at-company.com"
flagsobject
created_atstring(date-time)

Timestamp of record creation.
ISO8601 formatted time (UTC).

Example: "2020-09-01T08:29:00Z"
updated_atstring(date-time)

Timestamp of last modification of record.
ISO8601 formatted time (UTC).

Example: "2020-09-01T08:29:00Z"
Response
application/json
{
  "id": 63,
  "idp_id": "internal-identifier-at-company.com",
  "flags": {
    "deleted": false
  },
  "created_at": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z"
}

List Subscribers

Request

Filters and returns Subscribers for current Hub with basic info.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

Query
deletedstring

Filters subscribers by deletion status:

  • true - return only subscribers that were deleted,
  • false - return only subscribers that were not deleted,
  • all - return subscribers without filtering by deleted status.

Please note that this filter work on subscriber level and does not check subscriptions deletion status during filtering.

Default "false"
Enum"true""false""all"
qstring

String that filters subscribers to those containing the search string in:

  • idp_id.
Example: q=internal-identifier-at-company.com
sort_propstring

Determines which property results should be sorted by.

Default "created_at"
Enum"created_at""updated_at"
sort_dirstring

Determines sorting direction.

Default "desc"
Enum"asc""desc"
pageinteger>= 1

Requested page index.

Default 1
per_pageinteger[ 1 .. 100 ]

A limit on the number of records to be returned.

Default 25
api_versionstring

Api version

Value"V3-R1"
curl -i -X GET \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/subscribers?deleted=true&q=internal-identifier-at-company.com&sort_prop=created_at&sort_dir=asc&page=1&per_page=25&api_version=V3-R1' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
current_pageinteger>= 1
Example: 1
page_countinteger>= 1
Example: 4
per_pageinteger[ 1 .. 100 ]
Example: 25
totalinteger>= 0
Example: 1024
dataArray of objects<= 100 items
Response
application/json
{
  "current_page": 1,
  "page_count": 4,
  "per_page": 25,
  "total": 1024,
  "data": [
    { … }
  ]
}

Retrieve a Subscriber

Request

Returns data about single Subscriber.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

subscriber_idintegerrequired

id of the subscriber

Query
api_versionstring

Api version

Value"V3-R1"
curl -i -X GET \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/subscribers/{subscriber_id}?api_version=V3-R1' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idinteger>= 1
Example: 63
idp_idstring or null

Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.

Example: "internal-identifier-at-company.com"
flagsobject
created_atstring(date-time)

Timestamp of record creation.
ISO8601 formatted time (UTC).

Example: "2020-09-01T08:29:00Z"
updated_atstring(date-time)

Timestamp of last modification of record.
ISO8601 formatted time (UTC).

Example: "2020-09-01T08:29:00Z"
Response
application/json
{
  "id": 63,
  "idp_id": "internal-identifier-at-company.com",
  "flags": {
    "deleted": false
  },
  "created_at": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z"
}

Subscriber Subscription

Individual subscription. It's an unique combination of:

  • Address,
  • Subscription method,
  • Hub.
Operations

Subscription

Individual subscription. It's an unique combination of:

  • Address,
  • Subscription method,
  • Hub.
Operations