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

List Incidents

Request

Filters and returns Incident records for current Hub with basic info.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

Query
created_by_mestring

Behavior:

  • true - filter events to only those which were created by current user,
  • false - filter events to only those which were not created by current user,
  • all - don't filter events by creator.
Default "all"
Enum"true""false""all"
draftstring

Filters events by presence of unpublished Incident Update:

  • true - return only events containing at least one unpublished (draft) Incident Update,
  • false - return only events without any unpublished Incident Updates,
  • all - return events without filtering by draft status.
Default "false"
Enum"true""false""all"
incident_typesstring

Comma-separated names of incident types.
Filters incidents by status of last (including draft) update. Examples:

  • incident_types=monitoring
  • incident_types=investigating,identified

Possible incident type values:

  • identified,
  • investigating,
  • monitoring,
  • resolved.

When not set, do not filter incidents by type of last update.

publishedstring

Filter events by status of publication on Hub Page:

  • true - return only events published on Hub Page,
  • false - return only events that were not published on Hub Page.
  • all - don't filter events by publication status.
Default "all"
Enum"true""false""all"
unconfirmedstring

Filter events by state of the event:

  • true - return only events were published as unconfirmed on Hub Page,
  • false - return only events were published as confirmed on Hub Page.
  • all - don't filter events by unconfirmed status.
Default "all"
Enum"true""false""all"
archivedstring

Filters incidents by archived status:

  • true - return only incidents that were archived,
  • false - return only incidents that were not archived,
  • all - return incidents without filtering by archived status.
Default "false"
Enum"true""false""all"
deletedstring

Filters incidents by deletion status:

  • true - return only incidents that were deleted,
  • false - return only incidents that were not deleted,
  • all - return incidents without filtering by deleted status.
Default "false"
Enum"true""false""all"
sort_propstring

Determines which property results should be sorted by.

Default "start_time"
Enum"created_at""start_time""updated_at"
sort_dirstring

Determines sorting direction.

Default "desc"
Enum"asc""desc"
period_namestring

Comma-separated period names.
Filters event by period name.

Examples:

  • period_name=current
  • period_name=past,current

Possible period name values:

  • past,
  • current.

When not set, do not filter by period.

service_idsstring

Comma-separated string of service ids.

Filters events by at least one affected service, specified in params.

Example: service_ids=1,2,3

service_statusesstring

Comma-separated string of service statuses names.

Filters events by at least one affected service with specified status.

Examples:

  • service_statuses=degraded-performance
  • service_statuses=up,down

Possible incident type values:

  • up
  • degraded-performance
  • down
start_timestring(date-time)

Lower limit of the event start time filter.
ISO8601 formatted time (UTC).

Assumed as far in the past when not provided.
Combined with end_time filter events to those which period of occurrence (from event start_time to event end_time with end_time being far in the future for open incidents) overlaps with start_time and end_time params.

Default "1900-01-01T00:00:00Z"
end_timestring(date-time)

Upper limit of the event end time filter.
ISO8601 formatted time (UTC).

Assumed as far in the future when not provided.
Combined with start_time filter events to those which period of occurrence (from event start_time to event end_time with end_time being far in the future for open incidents) overlaps with start_time and end_time params.

Default "2199-01-01T00:00:00Z"
qstring

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

  • title,
  • body.
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
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}/incidents?created_by_me=true&draft=true&incident_types=string&published=true&unconfirmed=true&archived=true&deleted=true&sort_prop=created_at&sort_dir=asc&period_name=string&service_ids=string&service_statuses=string&start_time=1900-01-01T00%3A00%3A00Z&end_time=2199-01-01T00%3A00%3A00Z&q=string&extend=flags&page=1&per_page=25&api_version=V3-R1' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

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": [
    { … }
  ]
}

Retrieve an Incident

Request

Returns data about single Incident.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

incident_idintegerrequired

id of the requested incident.

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}?extend=flags&api_version=V3-R1' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE'

Responses

OK

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

Author email

titlestring

Title of incident as visible on Hub Page.
If there is draft IncidentUpdate that changes the title, the title will not reflect this change because the draft update is not published and therefore not visible on Hub Page.

created_atstring(date-time)

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

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

Timestamp of the start_time of the first (by start_time) 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"
end_timestring or null(date-time)

Timestamp of event end. If not set it means that the event has not ended yet.
ISO8601 formatted time (UTC).

Example: "2020-09-01T08:29:00Z"
flagsBasic flags (object) or Extended flags (object)
One of:
Response
application/json
{
  "id": 15,
  "author": "string",
  "title": "string",
  "created_at": "2020-09-01T08:29:00Z",
  "start_time": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z",
  "end_time": "2020-09-01T08:29:00Z",
  "flags": {
    "deleted": true,
    "draft": true
  }
}

Delete an Incident

Request

Deletes Incident 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.

Query
api_versionstring

Api version

Value"V3-R1"
curl -i -X DELETE \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/incidents/{incident_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"
}

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

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