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