StatusHub Management API (3.0-R1)

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 to StatusHub Control Panel.
For example if team members sign in to 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 in to 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 bound to the API Key used for authentication.
When the rate limit is 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 methods may have different rate limits which will be mentioned in the API method description.

Time zones

All date/time parameters should be passed in UTC timezone regardless of the default Hub timezone 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 the future due to incident still being open> and
<2025-03-01 00:00:00 UTC, far in the future due to not providing end_time> overlap in
<2025-03-01 00:00:00 UTC, far in the 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