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

Create an Incident

Request

Creates a new Incident. During creation, first Incident Update for this Incident will also be created.

Security

ApiKeyAuth

Path

subdomainstringrequired

Unique subdomain of requested Hub.

Query

api_versionstring

Api version

Value"V3-R1"

Bodyapplication/json

titlestringrequired

Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.

Example: "Title of the event"

start_timestring or null(date-time)required

Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).

Example: "2020-09-01T08:29:00Z"

incident_typestringrequired

Type of Incident Update.
Exact meaning may depend on use case and there is just one restriction:
resolved can't be used as type of a first (by start_time) Incident Update.

Enum"investigating""identified""monitoring""resolved"

Example: "investigating"

service_statusesArray of objectsrequired

Describes affected services and their statuses.

service_statuses[].service_idinteger

Example: 1234

service_statuses[].statusstring

Enum"up""degraded-performance""down"

Example: "down"

bodystring

Default ""

Example: "Message for an event or event update.<br>\nMay contain basic HTML tags.\n"

silentboolean

When true notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.

Default false

statestring or null

State of Incident or Incident Update:

draft - Not published on Hub Page,
unconfirmed - Published on Hub Page but marked as unconfirmed,
published - Published on Hub Page.

Default "published"

Enum"draft""unconfirmed""published"

Example: "published"

original_incident_idinteger>= 1

Used when creating a follow-up incident. Indicated the incident to which current incident is a follow-up.
Original Incident ID has to be resolved.

Example: 102

curl -i -X POST \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/incidents?api_version=V3-R1' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Title of the event",
    "start_time": "2020-09-01T08:29:00Z",
    "incident_type": "investigating",
    "service_statuses": [
      {
        "service_id": 1234,
        "status": "down"
      }
    ],
    "body": "Message for an event or event update.<br>\nMay contain basic HTML tags.\n",
    "silent": false,
    "state": "published",
    "original_incident_id": 102
  }'

Responses

Bodyapplication/json

idinteger>= 1

Example: 11

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)

Timestamps of a start_time of first (by start_time) Incident Update start_time.
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": 11,
  "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
  }
}

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

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 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json

idinteger>= 1

Example: 11

authorstring or null

Author email

titlestring

created_atstring(date-time)

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

Example: "2020-09-01T08:29:00Z"

start_timestring(date-time)

Timestamps of a start_time of first (by start_time) Incident Update start_time.
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": 11,
  "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
  }
}

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

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

Create an Incident

Request

Responses

Was this helpful?

List Incidents

Request

Responses

Was this helpful?

Retrieve an Incident

Request

Responses

Was this helpful?

Incident Update

Maintenance

Incident Update Template

Maintenance Template

Platform Alert

Hub

Hub Privacy

Assets

Group

Service

Connected Group

Connected Service

Subscriber

Subscriber Subscription

Subscription

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

Create an Incident

RequestExpand all

Responses

Was this helpful?

List Incidents

Request

Responses

Was this helpful?

Retrieve an Incident

Request

Responses

Was this helpful?

Incident Update

Maintenance

Incident Update Template

Maintenance Template

Platform Alert

Hub

Hub Privacy

Assets

Group

Service

Connected Group

Connected Service

Subscriber

Subscriber Subscription

Subscription

Request