Skip to content

StatusHub Management API (3.0-R1)

The StatusHub Management API v3

StatusHub Management API V3 is a REST API intended to be an alternative to StatusHub Control Panel web interface.
Example use cases:

  • Automation of incidents creation and update,
  • Automation of Hub services management,
  • Automation of creation and deletion of Connected Hubs.

Previous API versions

StatusHub Management API V3 replaces the Management API V2 which is now deprecated.
Management API V2 documentation has been moved to a new address:
https://api-v2-docs.statushub.com

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 providing end time will return the event because there is an overlap of both ranges:
<2025-02-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 consists 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

Retrieve an Incident Update

Request

Returns data about single Incident Update event.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

incident_idintegerrequired

id of the requested incident.

incident_update_idintegerrequired

id of the requested incident update

Query
extendstring

Specifies which properties should be expanded.
Expanded properties contains more detailed information which is less frequently needed in typical usage.
Currently supported only for flags.

Example: extend=flags
api_versionstring

Api version

Value"V3-R1"
curl -i -X GET \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/incidents/{incident_id}/incident_updates/{incident_update_id}?extend=flags&api_version=V3-R1' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idinteger>= 1
Example: 25
authorstring or null

Author email

titlestring

Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.

bodystring
Default ""
Example: "Message for an event or event update.<br>\nMay contain basic HTML tags.\n"
created_atstring(date-time)

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

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

Timestamps of a Incident Update.
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"
incident_typestring

Type of Incident Update.
Exact meaning may depend on use case and there is just one restriction:
resolved can't be used as type of a first (by start_time) Incident Update.

Enum"investigating""identified""monitoring""resolved"
Example: "investigating"
statestring or null

State of Incident or Incident Update:

  • draft - Not published on Hub Page,
  • unconfirmed - Published on Hub Page but marked as unconfirmed,
  • published - Published on Hub Page.
Default "published"
Enum"draft""unconfirmed""published"
Example: "published"
service_statusesArray of objects
flagsBasic flags (object) or Extended flags (object)
One of:
Response
application/json
{
  "id": 25,
  "author": "string",
  "title": "string",
  "body": "Message for an event or event update.<br>\nMay contain basic HTML tags.\n",
  "created_at": "2020-09-01T08:29:00Z",
  "start_time": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z",
  "incident_type": "investigating",
  "state": "published",
  "service_statuses": [
    { … }
  ],
  "flags": {
    "deleted": true,
    "draft": true
  }
}

Update an Incident Update

Request

Modifies existing Incident Update. Only modified attributes may be passed in payload. All other attributes will remain unchanged.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

incident_idintegerrequired

id of the requested incident.

incident_update_idintegerrequired

id of the requested incident update

Query
api_versionstring

Api version

Value"V3-R1"
Bodyapplication/json
titlestring

Title of this update.
Can contain only plain text.
Setting title to value different from current title of Incident may result in changing of Incident title.
Incident title equals to title of latest (by start_time) published (not draft) Incident Update title.

start_timestring or null(date-time)

Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).

Example: "2020-09-01T08:29:00Z"
incident_typestring

Type of Incident Update.
Exact meaning may depend on use case and there is just one restriction:
resolved can't be used as type of a first (by start_time) Incident Update.

Enum"investigating""identified""monitoring""resolved"
Example: "investigating"
service_statusesArray of objects

Describes affected services and their statuses.

bodystring
Default ""
Example: "Message for an event or event update.<br>\nMay contain basic HTML tags.\n"
silentboolean

When true notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.

Default false
statestring or null

State of Incident or Incident Update:

  • draft - Not published on Hub Page,
  • unconfirmed - Published on Hub Page but marked as unconfirmed,
  • published - Published on Hub Page.
Default "published"
Enum"draft""unconfirmed""published"
Example: "published"
curl -i -X PUT \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/incidents/{incident_id}/incident_updates/{incident_update_id}?api_version=V3-R1' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "body": "New incident update message."
  }'

Responses

OK

Bodyapplication/json
idinteger>= 1
Example: 25
authorstring or null

Author email

titlestring

Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.

bodystring
Default ""
Example: "Message for an event or event update.<br>\nMay contain basic HTML tags.\n"
created_atstring(date-time)

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

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

Timestamps of a Incident Update.
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"
incident_typestring

Type of Incident Update.
Exact meaning may depend on use case and there is just one restriction:
resolved can't be used as type of a first (by start_time) Incident Update.

Enum"investigating""identified""monitoring""resolved"
Example: "investigating"
statestring or null

State of Incident or Incident Update:

  • draft - Not published on Hub Page,
  • unconfirmed - Published on Hub Page but marked as unconfirmed,
  • published - Published on Hub Page.
Default "published"
Enum"draft""unconfirmed""published"
Example: "published"
service_statusesArray of objects
flagsBasic flags (object) or Extended flags (object)
One of:
Response
application/json
{
  "id": 25,
  "author": "string",
  "title": "string",
  "body": "Message for an event or event update.<br>\nMay contain basic HTML tags.\n",
  "created_at": "2020-09-01T08:29:00Z",
  "start_time": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z",
  "incident_type": "investigating",
  "state": "published",
  "service_statuses": [
    { … }
  ],
  "flags": {
    "deleted": true,
    "draft": true
  }
}

Delete an Incident Update

Request

Deletes Incident Update record. Records are soft-deleted which means that such deleted record can still be viewed or potentially restored.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

incident_idintegerrequired

id of the requested incident.

incident_update_idintegerrequired

id of the requested incident update

Query
api_versionstring

Api version

Value"V3-R1"
curl -i -X DELETE \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/incidents/{incident_id}/incident_updates/{incident_update_id}?api_version=V3-R1' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
messagestring
Response
application/json

Operation was successful.

{
  "message": "OK"
}

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 customer-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 notifications 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

Allows managing various methods limiting access to a Hub Page.

User-based methods - only one can be active in the same time:

  • SAML 2.0 - Recommended method offering the most flexibility and security,
  • Google OAuth - Use email address domain of user Google Account to limit the access to only those domains which are whitelisted.
    Very easy to setup for companies using Google services,
  • Hub Password - Most basic method which use a single password that can be used by anyone in order to see the Hub Page.

Network-based methods:

  • IP whitelist - Allow to specify a whitelist of IP V4 addresses and IP V4 ranges from which users are allowed to access the Hub Page.
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

Service Integration

Service Integration allows creation automation that creates events in StatusHub from various 3rd party applications.
As opposed to StatusHub Management API, those integrations endpoints are simplified and doesn't allow reading any data.
Most of integrations use per-service token for authorization.

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

External Application

Allows managing StatusHub widgets. Currently supported applications are:

  • Minimal Widget - Small and basic version of StatusHub widget intended to be used in places requiring small visual size of the widget,
  • Widget - Default Statushub widget,
  • Zendesk - StatusHub App for Zendesk - Zendesk Marketplace link
Operations

Uptime

Returns uptime information about:

  • Hub with either one value or per-day granularity,
  • Single group,
  • Single service.

Uptime is calculated according to following rules:

  • UTC timezone is used,
  • 'degraded-performance' is not counted towards downtime. Only 'down' status is treated as time when service was down,
  • If multiple events affect service in the same time, always worst status is being used for uptime calculation,
  • For group uptime, combination of worst statuses of all services in that group is used. For example, if group has three services and:
    • One was up for the whole time,
    • Second was down for the whole first half of the period (50%),
    • Last service was down for the second half of the period (50%), then group uptime is 0% because there was no time when none of its services were down.
  • For Hub uptime, combination of worst statuses of all services of that Hub is being used.
Operations

Subscription

Individual subscription. It's a unique combination of:

  • Address,
  • Subscription method,
  • Hub.

Events created on a Hub Page depending on configuration will be sent to subscriptions of that Hub.
Subscription can be created for only a subset of Hub services which will result in not receiving notifications about events affecting services that were not selected.

In order to create or manage multiple subscriptions that should be associated with the same person or entity, it's recommended to use Subscriber and Subscriber Subscription endpoints.

Operations

Subscriber

Subscriber represents a consumer of StatusHub notifications that can have multiple subscriptions.
Those endpoints are typically used in one of two situations:

  • User is interested in subscriptions only for specific person or entity instead of seeing or managing subscriptions for the whole Hub,
  • SAML Hub protection method is being used. This results in subscriber record containing SAML NameID value in idp_id field.
Operations

Subscriber Subscription

Equivalent of Subscription endpoints but with scope limited to single Subscriber record which id is provided in request path.

Operations