Skip to content

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

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

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

List Maintenance Templates

Request

Filters and returns Maintenance Template 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"
deletedstring

Filters templates by deletion status:

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

Query string

q_labelstring

Query label

sort_propstring

Determines which property results should be sorted by.

Default "created_at"
Value"created_at"
sort_dirstring

Determines sorting direction.

Default "desc"
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}/maintenance_templates?created_by_me=true&deleted=true&q=string&q_label=string&sort_prop=created_at&sort_dir=asc&page=1&per_page=25&api_version=V3-R1' \
  -H 'Authorization: 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 a Maintenance Template

Request

Returns data about single template.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

maintenance_template_idintegerrequired

id of the requested Maintenance Template

Query
api_versionstring

Api version

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

Responses

OK

Bodyapplication/json
idinteger>= 1
Example: 56
titlestring or null

Title of event.
Templates without title set will ignore event title when applied.

labelsArray of strings

List of labels for this template.

flagsobject
durationinteger or null[ 1 .. 5999 ]

Duration of maintenance in minutes.

bodystring or null

Title of event.
Templates without body set will ignore event body when applied.

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"
authorstring or null

Author email

service_statusesArray of objects
Response
application/json
{
  "id": 56,
  "title": "string",
  "labels": [
    "string"
  ],
  "flags": {
    "deleted": true,
    "silent": true
  },
  "duration": 1,
  "body": "string",
  "created_at": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z",
  "author": "string",
  "service_statuses": [
    { … }
  ]
}

Update a Maintenance Template

Request

Modifies an existing template. Only modified attributes may be passed in payload. All other attributes will remain unchanged.

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

maintenance_template_idintegerrequired

id of the requested Maintenance Template

Query
api_versionstring

Api version

Value"V3-R1"
Bodyapplication/json
titlestring or null

Title of event. Can be omitted if body is provided.

Can contain only plain text. HTML tags and other forms of formatting are not allowed.
Templates without title set will ignore event title when applied.

bodystring or null

Title of event. Can be omitted if title is provided.

Can contain basic HTML tags and is being interpreted as HTML.
Templates without body set will ignore event body when applied.

durationinteger or null[ 1 .. 5999 ]

Duration of maintenance in minutes.
Maximum allowed value is 99h:59min (5999 minutes).

labelsArray of strings

List of labels for this template. Template can have many labels.
If passing just one label, it should still be passed as an array: "labels": ["some label value"].

service_statusesArray of objects

Describes affected services and their statuses.

silentboolean or null

Controls silent parameter value when applying the template:

  • true - Set event silent parameter as true,
  • false - Set event silent parameter as false,
  • null - Do not set event silent parameter.
curl -i -X PUT \
  'https://{accountsubdomain}.app.statushub.io/api/v3/hubs/{subdomain}/maintenance_templates/{maintenance_template_id}?api_version=V3-R1' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "string",
    "body": "string",
    "duration": 1,
    "labels": [
      "string"
    ],
    "service_statuses": [
      {
        "service_id": 1234,
        "status": "down"
      }
    ],
    "silent": true
  }'

Responses

OK

Bodyapplication/json
idinteger>= 1
Example: 56
titlestring or null

Title of event.
Templates without title set will ignore event title when applied.

labelsArray of strings

List of labels for this template.

flagsobject
durationinteger or null[ 1 .. 5999 ]

Duration of maintenance in minutes.

bodystring or null

Title of event.
Templates without body set will ignore event body when applied.

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"
authorstring or null

Author email

service_statusesArray of objects
Response
application/json
{
  "id": 56,
  "title": "string",
  "labels": [
    "string"
  ],
  "flags": {
    "deleted": true,
    "silent": true
  },
  "duration": 1,
  "body": "string",
  "created_at": "2020-09-01T08:29:00Z",
  "updated_at": "2020-09-01T08:29:00Z",
  "author": "string",
  "service_statuses": [
    { … }
  ]
}

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