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

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

List Services

Request

Filters and returns services for current Hub.
Can return services from all groups.
Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub.

Security

ApiKeyAuth

Path

subdomainstringrequired

Unique subdomain of requested Hub.

Query

group_idinteger>= 1

Filters services to only those which belong to group with ID specified by group_id.

archivedstring

Filters services by archived status:

true - return only services that were archived,
false - return only services that were not archived,
all - return services without filtering by archived status.

Default "false"

Enum"true""false""all"

deletedstring

Filters services by deletion status:

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

Default "false"

Enum"true""false""all"

qstring

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

name,
custom_id.

per_group_sortboolean

Alters behavior of sort_prop:

(default) If per_group_sort is true - Sort by the sort_prop in each connected group individually,
if per_group_sort is false - Sort by sort_prop globally so output will contain connected services ignoring the order of connected groups.
This means that connected services from same connected group may be interleaved by connected services from different connected groups.
One exception is position sort_prop which forces per_group_sort to be true regardless of actual value used in request.
If per_group_sort is true the order of connected groups is always determined by connected group position.

Default true

sort_propstring

Determines which property results should be sorted by.
The final sorting depends also on per_group_sort parameter:

(default) If per_group_sort is true - Sort by the sort_prop in each group individually,
if per_group_sort is false - Sort by sort_prop globally so output will contain services ignoring the order of group.
This means that services from same group may be interleaved by services from different groups.
One exception is position sort_prop which forces per_group_sort to be true regardless of actual value used in request.

If per_group_sort is true the order of groups is always determined by group position.

Default "position"

Enum"position""created_at""updated_at"

sort_dirstring

Determines sorting direction inside each Group.
It does not affect the order of groups which is fixed to position.
Services will be sorted by sort_prop inside each group individually.

Default "asc"

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}/services?group_id=1&archived=true&deleted=true&q=string&per_group_sort=true&sort_prop=position&sort_dir=asc&page=1&per_page=25&api_version=V3-R1' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

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

Response

application/json

{
  "current_page": 1,
  "page_count": 4,
  "per_page": 25,
  "total": 1024,
  "data": [
    { … }
  ]
}

Create a Service

Request

Creates new service in a group.
Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub.

Security

ApiKeyAuth

Path

subdomainstringrequired

Unique subdomain of requested Hub.

Query

api_versionstring

Api version

Value"V3-R1"

Bodyapplication/json

custom_idstring or null

custom_id is a property that can be used to assign an external identifier to a service. This identifier can be used to for example synchronize monitored entities with services in StatusHub.
custom_id has to be unique in scope of a Hub.

descriptionstring or null

description can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.

group_idinteger>= 1required

namestringrequired

public_namestring or null

public_name is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use name describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use public_name with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.

curl -i -X POST \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/services?api_version=V3-R1' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "custom_id": "string",
    "description": "string",
    "group_id": 1,
    "name": "string",
    "public_name": "string"
  }'

Responses

Bodyapplication/json

custom_idstring or null

descriptionstring or null

description can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.

group_idinteger>= 1

Example: 102

idinteger>= 1

Example: 103

namestring

public_namestring or null

tokenstring

Unique token value that is being used to connected external integrations to StatusHub.
Typically all integration URLs are using the token value so knowing the token value allows to construct various integrations URLs programmatically.

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"

flagsobject

Response

application/json

{
  "custom_id": "string",
  "description": "string",
  "group_id": 102,
  "id": 103,
  "name": "string",
  "public_name": "string",
  "token": "string",
  "created_at": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z",
  "flags": {
    "archived": true,
    "deleted": true
  }
}

Retrieve a Service

Request

Returns data about single service.
Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub.

Security

ApiKeyAuth

Path

subdomainstringrequired

Unique subdomain of requested Hub.

service_idinteger>= 1required

ID of Service

Query

api_versionstring

Api version

Value"V3-R1"

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

Responses

Bodyapplication/json

custom_idstring or null

descriptionstring or null

description can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.

group_idinteger>= 1

Example: 102

idinteger>= 1

Example: 103

namestring

public_namestring or null

tokenstring

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"

flagsobject

Response

application/json

{
  "custom_id": "string",
  "description": "string",
  "group_id": 102,
  "id": 103,
  "name": "string",
  "public_name": "string",
  "token": "string",
  "created_at": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z",
  "flags": {
    "archived": true,
    "deleted": true
  }
}

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

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

StatusHub Public API (3.0-R1)

The StatusHub Public API v3

Work in progress

StatusHub regions and API URL

EU region

Rate limiting

Time zones

Filtering events by time range

Extended properties

Incident

Incident Update

Maintenance

Incident Update Template

Maintenance Template

Platform Alert

Hub

Hub Privacy

Assets

Group

Service

List Services

Request

Responses

Was this helpful?

Create a Service

Request

Responses

Was this helpful?

Retrieve a Service

Request

Responses

Was this helpful?

Connected Group

Connected Service

Subscriber

Subscriber Subscription

Subscription