StatusHub Management API V3 is a REST API intended to be an alternative to StatusHub Control Panel web interface.
Example use cases:
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
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
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
StatusHub API has two rate limits:
Rate limit is bounded to API Key used for authentication.
When rate limit will be exceeded, StatusHub API will respond with:
{"error":"Too many requests - please retry later"} responseIn special cases certain API method may have different rate limit which will be mentioned in API method description.
All date/time parameters should be passed in UTC zone no matter the default zone Hub settings.
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:
start_time assumes end_time as far in the future,end_time assumes start_time as far in the past.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>.
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:
/api/v3/hubs/hub-subdomain/maintenances,/api/v3/hubs/hub-subdomain/maintenances?extend=flagshttps://{accountSubdomain}.app.statushub.io/api/v3/
https://{accountSubdomain}.app-eu1.statushub.io/api/v3/
Incident is a most important event type.
Incident represents an event that:
resolved Incident Update is created for this incident,resolved incident type.Most typical use case:
monitoring incident type is being created while team is keeping an eye on service health,resolved incident type is being created which ends the Incident.Maintenance represents an event that:
Most typical use case:
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.
Allows managing various methods limiting access to a Hub Page.
User-based methods - only one can be active in the same time:
Network-based methods:
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.
Allows managing StatusHub widgets. Currently supported applications are:
Returns uptime information about:
Uptime is calculated according to following rules:
Individual subscription. It's a unique combination of:
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.
Subscriber represents a consumer of StatusHub notifications that can have multiple subscriptions.
Those endpoints are typically used in one of two situations:
idp_id field.