# StatusHub Management API # 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](https://api-v2-docs.statushub.com) ## StatusHub regions and API URL All API requests should be made on hostname used to sign in to StatusHub Control Panel.
For example if team members sign in to 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 in to 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 bound to the API Key used for authentication.
When the rate limit is 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 methods may have different rate limits which will be mentioned in the API method description. ## Time zones All date/time parameters should be passed in UTC timezone regardless of the default Hub timezone 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 the future due to incident still being open> and
<2025-03-01 00:00:00 UTC, far in the future due to not providing `end_time`> overlap in
<2025-03-01 00:00:00 UTC, far in the 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` Version: 3.0-R1 ## Servers Main US region ``` https://{accountSubdomain}.app.statushub.io/api/v3 ``` Variables: - `accountSubdomain`: Unique subdomain of your account Default: "subdomain-of-your-account" EU region ``` https://{accountSubdomain}.app-eu1.statushub.io/api/v3 ``` Variables: - `accountSubdomain`: Unique subdomain of your account Default: "subdomain-of-your-account" ## Security ### ApiKeyAuth Type: apiKey In: header Name: X-API-KEY ## Download OpenAPI description [StatusHub Management API](https://api-docs.statushub.com/_bundle/api-v3-openapi.yaml) ## 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. ### Create an Incident - [POST /hubs/{subdomain}/incidents](https://api-docs.statushub.com/api-v3-openapi/incident/createincident.md): Creates a new Incident. During creation, first Incident Update for this Incident will also be created. ### List Incidents - [GET /hubs/{subdomain}/incidents](https://api-docs.statushub.com/api-v3-openapi/incident/listincidents.md): Filters and returns Incident records for current Hub with basic info. ### Retrieve an Incident - [GET /hubs/{subdomain}/incidents/{incident_id}](https://api-docs.statushub.com/api-v3-openapi/incident/getincident.md): Returns data about single Incident. ### Delete an Incident - [DELETE /hubs/{subdomain}/incidents/{incident_id}](https://api-docs.statushub.com/api-v3-openapi/incident/deleteincident.md): Deletes Incident record. Records are soft-deleted which means that such deleted record can still be viewed or potentially restored. ## 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. ### Create an Incident Update - [POST /hubs/{subdomain}/incidents/{incident_id}/incident_updates](https://api-docs.statushub.com/api-v3-openapi/incident-update/createincidentincidentupdate.md): Creates a new Incident Update. Incident Update is a distinct update in an Incident. Creation of Incident Update records is a way to add new update to an existing Incident. ### List Incident Updates - [GET /hubs/{subdomain}/incidents/{incident_id}/incident_updates](https://api-docs.statushub.com/api-v3-openapi/incident-update/listincidentincidentupdates.md): Filters and returns Incident Update records for specific Incident and current Hub with basic info. ### Retrieve an Incident Update - [GET /hubs/{subdomain}/incidents/{incident_id}/incident_updates/{incident_update_id}](https://api-docs.statushub.com/api-v3-openapi/incident-update/getincidentincidentupdate.md): Returns data about single Incident Update event. ### Update an Incident Update - [PUT /hubs/{subdomain}/incidents/{incident_id}/incident_updates/{incident_update_id}](https://api-docs.statushub.com/api-v3-openapi/incident-update/updateincidentincidentupdate.md): Modifies existing Incident Update. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete an Incident Update - [DELETE /hubs/{subdomain}/incidents/{incident_id}/incident_updates/{incident_update_id}](https://api-docs.statushub.com/api-v3-openapi/incident-update/deleteincidentincidentupdate.md): Deletes Incident Update record. Records are soft-deleted which means that such deleted record can still be viewed or potentially restored. ## 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 the specific time frame. ### Create a Maintenance event - [POST /hubs/{subdomain}/maintenances](https://api-docs.statushub.com/api-v3-openapi/maintenance/createmaintenance.md): Creates a new Maintenance. ### List Maintenance events - [GET /hubs/{subdomain}/maintenances](https://api-docs.statushub.com/api-v3-openapi/maintenance/listmaintenances.md): Filters and returns Maintenance records for current Hub with basic info. ### Retrieve a Maintenance event - [GET /hubs/{subdomain}/maintenances/{maintenance_id}](https://api-docs.statushub.com/api-v3-openapi/maintenance/getmaintenance.md): Returns data about single maintenance event. ### Update a Maintenance event - [PUT /hubs/{subdomain}/maintenances/{maintenance_id}](https://api-docs.statushub.com/api-v3-openapi/maintenance/updatemaintenance.md): Modifies an existing Maintenance. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete a Maintenance event - [DELETE /hubs/{subdomain}/maintenances/{maintenance_id}](https://api-docs.statushub.com/api-v3-openapi/maintenance/deletemaintenance.md): Deletes Maintenance record. Records are soft-deleted which means that such deleted record can still be viewed or potentially restored. ## 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. ### Create an Incident Update Template - [POST /hubs/{subdomain}/incident_templates](https://api-docs.statushub.com/api-v3-openapi/incident-update-template/createincidentupdatetemplate.md): Creates a new template. Template don't have to contain values set for all possible fields. If there is no value present for one of the field, during applying the template such field will be ignored. ### List Incident Update Templates - [GET /hubs/{subdomain}/incident_templates](https://api-docs.statushub.com/api-v3-openapi/incident-update-template/listincidentupdatetemplates.md): Filters and returns Incident Template records for current Hub with basic info. ### Retrieve an Incident Update Template - [GET /hubs/{subdomain}/incident_templates/{incident_template_id}](https://api-docs.statushub.com/api-v3-openapi/incident-update-template/getincidentupdatetemplate.md): Returns data about single template. ### Update an Incident Update Template - [PUT /hubs/{subdomain}/incident_templates/{incident_template_id}](https://api-docs.statushub.com/api-v3-openapi/incident-update-template/updateincidentupdatetemplate.md): Modifies an existing template. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete an Incident Update Template - [DELETE /hubs/{subdomain}/incident_templates/{incident_template_id}](https://api-docs.statushub.com/api-v3-openapi/incident-update-template/deleteincidentupdatetemplate.md): Deletes Incident Template record. Records are soft-deleted which means that such deleted record can still be viewed. ## Maintenance Template Maintenance Template is used to create Maintenance event in StatusHub Control Panel quicker.
It can contain predefined: - title, - body, - duration, - service statuses. ### Create a Maintenance Template - [POST /hubs/{subdomain}/maintenance_templates](https://api-docs.statushub.com/api-v3-openapi/maintenance-template/createmaintenancetemplate.md): Creates a new template. Template don't have to contain values set for all possible fields. If there is no value present for one of the field, during applying the template such field will be ignored. ### List Maintenance Templates - [GET /hubs/{subdomain}/maintenance_templates](https://api-docs.statushub.com/api-v3-openapi/maintenance-template/listmaintenancetemplates.md): Filters and returns Maintenance Template records for current Hub with basic info. ### Retrieve a Maintenance Template - [GET /hubs/{subdomain}/maintenance_templates/{maintenance_template_id}](https://api-docs.statushub.com/api-v3-openapi/maintenance-template/getmaintenancetemplate.md): Returns data about single template. ### Update a Maintenance Template - [PUT /hubs/{subdomain}/maintenance_templates/{maintenance_template_id}](https://api-docs.statushub.com/api-v3-openapi/maintenance-template/updatemaintenancetemplate.md): Modifies an existing template. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete a Maintenance Template - [DELETE /hubs/{subdomain}/maintenance_templates/{maintenance_template_id}](https://api-docs.statushub.com/api-v3-openapi/maintenance-template/deletemaintenancetemplate.md): Deletes Maintenance Template record. Records are soft-deleted which means that such deleted record can still be viewed. ## 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. ### Show Platform Alert data - [GET /hubs/{subdomain}/platform_alert](https://api-docs.statushub.com/api-v3-openapi/platform-alert/paths/~1hubs~1%7Bsubdomain%7D~1platform_alert/get.md): Returns data about Platform Alert state. ### Set/Unset Platform Alert - [POST /hubs/{subdomain}/platform_alert](https://api-docs.statushub.com/api-v3-openapi/platform-alert/paths/~1hubs~1%7Bsubdomain%7D~1platform_alert/post.md): Sets Platform Alert state. Can be used to both set/enable the Platform Alert as well as to unset/disable it. ## Hub Hub is a central record that represents the status page and holds all related records. ### List of Hubs - [GET /hubs](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs/get.md): Filters and returns Hub records with basic info. ### Show Hub - [GET /hubs/{subdomain}](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D/get.md): Returns data about single Hub. ### Update hub - [PUT /hubs/{subdomain}](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D/put.md): Modifies basic settings of an existing Hub. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Hub services conditions overview - [GET /hubs/{subdomain}/status/counters](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1status~1counters/get.md): Returns Hub services conditions overview ### List of Connected Hubs - [GET /hubs/{subdomain}/connected_hubs](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1connected_hubs/get.md): Filters and returns Connected Hub records for current Primary Hub with basic info. Request valid only in scope of Primary Hub and can't be used in scope of a Connected Hub. ### Create a new Connected Hub - [POST /hubs/{subdomain}/connected_hubs](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1connected_hubs/post.md): Creates a new Connected Hub for current Primary Hub. Request valid only in scope of Primary Hub and can't be used in scope of a Connected Hub. ### Show Connected Hub - [GET /hubs/{subdomain}/connected_hubs/{connected_subdomain}](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1connected_hubs~1%7Bconnected_subdomain%7D/get.md): Returns data about single Connected Hub. ### Update Connected Hub - [PUT /hubs/{subdomain}/connected_hubs/{connected_subdomain}](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1connected_hubs~1%7Bconnected_subdomain%7D/put.md): Modifies basic settings of an existing Connected Hub. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete a Connected Hub - [DELETE /hubs/{subdomain}/connected_hubs/{connected_subdomain}](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1connected_hubs~1%7Bconnected_subdomain%7D/delete.md): Deletes Connected Hub record. ### Copy Connected Hub - [POST /hubs/{subdomain}/connected_hubs/{connected_subdomain}/copy](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1connected_hubs~1%7Bconnected_subdomain%7D~1copy/post.md): Creates a new Connected Hub with same settings as existing Connected Hub. Copying will preserve all configuration options which includes: - Hub properties (excluding custom domain) - Privacy settings - List of associated services and groups - Appearance settings - Notification settings - Features enabled by StatusHub support Copy will not copy events nor subscribers data. ### Show Hub appearance settings - [GET /hubs/{subdomain}/appearance](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1appearance/get.md): Returns data about Hub appearance settings. ### Update Hub appearance settings - [PUT /hubs/{subdomain}/appearance](https://api-docs.statushub.com/api-v3-openapi/hub/paths/~1hubs~1%7Bsubdomain%7D~1appearance/put.md): Modifies an existing Hub appearance settings. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ## 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. ### Retrieve Hub privacy state - [GET /hubs/{subdomain}/access_restriction](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction/get.md): Lists all available methods for restricting access to the Hub as well as the currently enabled access restriction method or public if Hub is public. ### Retrieve SAML settings - [GET /hubs/{subdomain}/access_restriction/saml](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1saml/get.md): Returns data about SAML authentication. ### Update SAML authentication settings - [PUT /hubs/{subdomain}/access_restriction/saml](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1saml/put.md): Modifies SAML authentication settings. ### Retrieve Google OAuth settings - [GET /hubs/{subdomain}/access_restriction/google_oauth](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1google_oauth/get.md): Returns data about Google OAuth authorization. ### Update Google OAuth authorization settings - [PUT /hubs/{subdomain}/access_restriction/google_oauth](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1google_oauth/put.md): Modifies Google OAuth authorization settings. ### Retrieve Hub password settings - [GET /hubs/{subdomain}/access_restriction/global_password](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1global_password/get.md): Returns data about Hub password. ### Update Hub password settings - [PUT /hubs/{subdomain}/access_restriction/global_password](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1global_password/put.md): Modifies Hub password settings. ### Retrieve domain-based restriction details - [GET /hubs/{subdomain}/access_restriction/domains_whitelist](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1domains_whitelist/get.md): Returns data about domain-based restriction for Hub access restriction methods providing authentication of user with user email. Applies to: - SAML - optional, - Google OAuth - required. Once set if visitor trying to sign-in has a domain reported by authentication method not matching any of the domains in domains whitelist, the access to Hub is not granted even if authentication method normally would grant access to this visitor. Required to be enabled when using Google OAuth restriction method. ### Update Hub domain-based restrictions - [PUT /hubs/{subdomain}/access_restriction/domains_whitelist](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1domains_whitelist/put.md): Modified the domain-based restrictions settings. ### Retrieve ip-based restriction details - [GET /hubs/{subdomain}/access_restriction/ip_whitelist](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1ip_whitelist/get.md): Returns data about ip-based restriction for Hub. If enabled only visitors from whitelisted IP addresser or IP ranges are allowed to access the Hub. All other visitors will see 404 error. Supported address formats: - IP V4 address, - IP V4 range in CIDR notation. ### Update Hub ip-based restrictions - [PUT /hubs/{subdomain}/access_restriction/ip_whitelist](https://api-docs.statushub.com/api-v3-openapi/hub-privacy/paths/~1hubs~1%7Bsubdomain%7D~1access_restriction~1ip_whitelist/put.md): Modified the ip-based restrictions settings. ## 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. ### Upload an asset - [POST /hubs/{subdomain}/assets](https://api-docs.statushub.com/api-v3-openapi/assets/paths/~1hubs~1%7Bsubdomain%7D~1assets/post.md): Uploads an asset for existing Hub. Currently supported assets are: - Logo, - Favicon. ### Delete an asset - [DELETE /hubs/{subdomain}/assets/{asset_id}](https://api-docs.statushub.com/api-v3-openapi/assets/paths/~1hubs~1%7Bsubdomain%7D~1assets~1%7Basset_id%7D/delete.md): Deletes an asset for current Hub. This method can be used to remove for example Logo from a Hub. ## Group Group purpose is to group Services in logical groups. ### List Groups - [GET /hubs/{subdomain}/groups](https://api-docs.statushub.com/api-v3-openapi/group/listgroups.md): Filters and returns Groups for current Hub. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. ### Create a Group - [POST /hubs/{subdomain}/groups](https://api-docs.statushub.com/api-v3-openapi/group/creategroup.md): Creates a new group. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. ### Retrieve a Group - [GET /hubs/{subdomain}/groups/{group_id}](https://api-docs.statushub.com/api-v3-openapi/group/getgroup.md): Returns data about single group. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. ### Update a Group - [PUT /hubs/{subdomain}/groups/{group_id}](https://api-docs.statushub.com/api-v3-openapi/group/updategroup.md): Updates existing group. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. ### Delete a Group - [DELETE /hubs/{subdomain}/groups/{group_id}](https://api-docs.statushub.com/api-v3-openapi/group/deletegroup.md): Deletes existing group and all its services. Request valid only in the scope of Primary or Standalone Hub and can't be used in the scope of a Connected Hub. Deleting a group also deletes: - All services in that group, - Events if there are events that after deleting this group with its services would be left without any other services. ### Archive a Group - [PUT /hubs/{subdomain}/groups/{group_id}/archive](https://api-docs.statushub.com/api-v3-openapi/group/archivegroup.md): Archives existing group and all its services. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. Deleting a group also archives: - All services in that group, - Events if there are events that after deleting this group with its services would be left without any other services. The difference between deleting and archiving can be summarized by: - Both archived and deleted records are not visible on Hub Page, - Unlike deleted records, archived records are still visible in Control Panel but as a read-only records. ### Update a Group position - [PUT /hubs/{subdomain}/groups/{group_id}/reorder](https://api-docs.statushub.com/api-v3-openapi/group/reordergroup.md): Updates position of existing group. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. ## 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. ### List Services - [GET /hubs/{subdomain}/services](https://api-docs.statushub.com/api-v3-openapi/service/listservices.md): 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. ### Create a Service - [POST /hubs/{subdomain}/services](https://api-docs.statushub.com/api-v3-openapi/service/createservice.md): Creates a 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. ### Retrieve a Service - [GET /hubs/{subdomain}/services/{service_id}](https://api-docs.statushub.com/api-v3-openapi/service/getservice.md): 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. ### Update a Service - [PUT /hubs/{subdomain}/services/{service_id}](https://api-docs.statushub.com/api-v3-openapi/service/updateservice.md): Updates data of a service. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. ### Delete a Service - [DELETE /hubs/{subdomain}/services/{service_id}](https://api-docs.statushub.com/api-v3-openapi/service/deleteservice.md): Deletes a service. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. Deletion is a soft deletion, service can be restored later. ### Archive a Service - [PUT /hubs/{subdomain}/services/{service_id}/archive](https://api-docs.statushub.com/api-v3-openapi/service/archiveservice.md): Archives a service. Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub. Archived services are not returned by index endpoint unless archived parameter is set to true. ### Update a Service position - [PUT /hubs/{subdomain}/services/{service_id}/reorder](https://api-docs.statushub.com/api-v3-openapi/service/reorderservice.md): Updates position of a 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. ## 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. ### List service integrations - [GET /hubs/{subdomain}/services/{service_id}/integrations](https://api-docs.statushub.com/api-v3-openapi/service-integration/listserviceintegrations.md): List all of available integrations for a service. Integration version is used to indicate the generation of integrations where v1 are the basic integrations available in StatusHub for long time. while v2 integrations are much more capable and all newly introduced integrations will be added in v2 version. ### Retrieve a service integration details - [GET /hubs/{subdomain}/services/{service_id}/integrations/{integration_slug}](https://api-docs.statushub.com/api-v3-openapi/service-integration/showserviceintegration.md): Show service integration details With the exception of Pingdom integration, all other integrations are using per-service URL for connection. ### Update service integrations - [PUT /hubs/{subdomain}/services/{service_id}/integrations/{integration_slug}](https://api-docs.statushub.com/api-v3-openapi/service-integration/updateserviceintegration.md): Update service integrations ## Connected Group Connected Group is a special representation of actual Group that through its Services is attached to Connected Hub. ### List Connected Groups - [GET /hubs/{subdomain}/connected_groups](https://api-docs.statushub.com/api-v3-openapi/connected-group/listconnectedgroups.md): Filters and returns Connected Groups for current Hub. Request valid only in scope of Connected Hub and can't be used in scope of a Primary or Standalone Hub. ### Retrieve a Connected Group - [GET /hubs/{subdomain}/connected_groups/{group_id}](https://api-docs.statushub.com/api-v3-openapi/connected-group/getconnectedgroup.md): Returns data about single Connected Group. Request valid only in scope of Connected Hub and can't be used in scope of a Primary or Standalone Hub. ## Connected Service Connected Service is a special representation of actual Service that is attached to Connected Hub. ### List Connected Services - [GET /hubs/{subdomain}/connected_services](https://api-docs.statushub.com/api-v3-openapi/connected-service/listconnectedservices.md): Filters and returns Connected Services for current Hub. Request valid only in scope of Connected Hub and can't be used in scope of a Primary or Standalone Hub. ### Create a Connected Service - [POST /hubs/{subdomain}/connected_services](https://api-docs.statushub.com/api-v3-openapi/connected-service/createconnectedservice.md): Creates a new Connected Service. Request valid only in the scope of Connected Hub and can't be used in the scope of a Primary or Standalone Hub. ### Retrieve a Connected Service - [GET /hubs/{subdomain}/connected_services/{service_id}](https://api-docs.statushub.com/api-v3-openapi/connected-service/getconnectedservice.md): Returns data about single Connected Service. Request valid only in scope of Connected Hub and can't be used in scope of a Primary or Standalone Hub. ### Delete a Connected Service - [DELETE /hubs/{subdomain}/connected_services/{service_id}](https://api-docs.statushub.com/api-v3-openapi/connected-service/deleteconnectedservice.md): Deletes a Connected Service. Request valid only in the scope of Connected Hub and can't be used in the scope of a Primary or Standalone Hub. ## 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](https://www.zendesk.com/marketplace/apps/support/127482/statushub/) ### List External Application installations - [GET /hubs/{subdomain}/external_applications](https://api-docs.statushub.com/api-v3-openapi/external-application/listexternalapplications.md): List all of currently supported external applications as well as the status of the integration for current Hub. If app is not enabled, it will not work even if its installed with correct token. 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 ### Retrieve an external application installation details - [GET /hubs/{subdomain}/external_applications/{external_application_slug}](https://api-docs.statushub.com/api-v3-openapi/external-application/getexternalapplication.md): Show details of a specific External Application installation. For security reasons, token is not returned. If app token is lost, in Management API v3 the only way to retrieve a token is to generate a new one with reset token operation. In order to install the application, please refer to documentation of respective CP2 which will contain all necessary snippets and links. ### Update an External Application installation - [PUT /hubs/{subdomain}/external_applications/{external_application_slug}](https://api-docs.statushub.com/api-v3-openapi/external-application/updateexternalapplication.md): Updates External Application installation. Currently the only allowed operation is to enable or disable the app. ### Reset External Application token - [PUT /hubs/{subdomain}/external_applications/{external_application_slug}/reset_token](https://api-docs.statushub.com/api-v3-openapi/external-application/resetexternalapplicationtoken.md): Resets the token for an External Application installation. This is the only way to obtain app token through Management API v3. Resetting the token is automatically invalidating previously used token and that operation is unreverisble. Can be used to quickly disable the app if for example token has been compromised. ## 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. ### Retrieve Hub uptime value - [GET /hubs/{subdomain}/uptime](https://api-docs.statushub.com/api-v3-openapi/uptime/getuptime.md): Returns uptime for a Hub which is based on uptime of all services in that Hub for a given date range. Hub is considered up if all of its services are not down. Every time frame when at least one of Hub services is down, is considered as downtime for this Hub. Maximum length of date range is 18 months. ### Returns Hub uptime data with daily granularity - [GET /hubs/{subdomain}/uptime/daily](https://api-docs.statushub.com/api-v3-openapi/uptime/getdailyuptime.md): Returns uptime for a Hub with daily granularity. Hub uptime is based on uptime of all services in that Hub for every day. Days are aligned to UTC timezone. Hub is considered up for given day if all of its services are not down in that day. Every time frame when at least one of Hub services is down, is considered as downtime for this Hub. Maximum length of date range is 18 months. ### Retrieve group uptime value - [GET /hubs/{subdomain}/uptime/groups/{group_id}](https://api-docs.statushub.com/api-v3-openapi/uptime/getgroupuptime.md): Returns uptime for a group which is based on uptime of all services in that group for a given date range. Group is considered up if all of its services are not down. Every time frame when at least one of group services is down, is considered as downtime for this group. Maximum length of date range is 18 months. ### Retrieve service uptime value - [GET /hubs/{subdomain}/uptime/services/{service_id}](https://api-docs.statushub.com/api-v3-openapi/uptime/getserviceuptime.md): Returns uptime for a service for a given date range. Service is considered up its status is not down. Maximum length of date range is 18 months. ## 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. ### Create a Subscription - [POST /hubs/{subdomain}/subscriptions](https://api-docs.statushub.com/api-v3-openapi/subscription/createsubscription.md): Creates a new Subscription. Creates Subscriber record as well. Besides regular validation - like address correctness - there are a few additional constraints: - Address has to be unique for current Hub, - Single Subscriber can't have multiple subscriptions with same method name. For example it's not allowed for one Subscriber to have for example two email subscriptions. ### List Subscriptions - [GET /hubs/{subdomain}/subscriptions](https://api-docs.statushub.com/api-v3-openapi/subscription/listsubscriptions.md): Filters and returns Subscriptions with basic info for current Hub. ### Retrieve a Subscription - [GET /hubs/{subdomain}/subscriptions/{subscription_id}](https://api-docs.statushub.com/api-v3-openapi/subscription/getsubscription.md): Returns data about single Subscription. ### Update a Subscription - [PUT /hubs/{subdomain}/subscriptions/{subscription_id}](https://api-docs.statushub.com/api-v3-openapi/subscription/updatesubscription.md): Modifies existing Subscription. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete a Subscription - [DELETE /hubs/{subdomain}/subscriptions/{subscription_id}](https://api-docs.statushub.com/api-v3-openapi/subscription/deletesubscription.md): Deletes Subscription record. Records are soft-deleted which means that such deleted record can still be viewed and potentially restored. If deleted Subscription is the last active subscription for Subscriber, Subscriber record is also deleted. ### Restore a Subscription - [PUT /hubs/{subdomain}/subscriptions/{subscription_id}/restore](https://api-docs.statushub.com/api-v3-openapi/subscription/restoresubscription.md): Restores deleted Subscription. May fail if restoring would result in record that is not valid for example because subscription with that address already exists. Restoring depending on data may either: - Recreate the record as a new one with new ID, - Undelete the record preserving it ID. ## 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. ### Create a Subscriber - [POST /hubs/{subdomain}/subscribers](https://api-docs.statushub.com/api-v3-openapi/subscriber/createsubscriber.md): Creates a new Subscriber. Main purpose of Subscriber is to create a record to which later one or many subscriptions can be added. One Subscriber can have multiple methods of communication associated with it. It also allows to set SAML NameID that can be then used to recognize Subscriber after sign-in into protected Hub Page. ### List Subscribers - [GET /hubs/{subdomain}/subscribers](https://api-docs.statushub.com/api-v3-openapi/subscriber/listsubscribers.md): Filters and returns Subscribers for current Hub with basic info. ### Retrieve a Subscriber - [GET /hubs/{subdomain}/subscribers/{subscriber_id}](https://api-docs.statushub.com/api-v3-openapi/subscriber/getsubscriber.md): Returns data about single Subscriber. ### Updates a Subscriber - [PUT /hubs/{subdomain}/subscribers/{subscriber_id}](https://api-docs.statushub.com/api-v3-openapi/subscriber/updatesubscriber.md): Modifies existing Subscriber. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete a Subscriber - [DELETE /hubs/{subdomain}/subscribers/{subscriber_id}](https://api-docs.statushub.com/api-v3-openapi/subscriber/deletesubscriber.md): Deletes Subscriber record. Records are soft-deleted which means that such deleted record can still be viewed. Deleting Subscriber also deletes all its Subscriptions. ## Subscriber Subscription Equivalent of Subscription endpoints but with scope limited to single Subscriber record which `id` is provided in request path. ### Create a Subscription - [POST /hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions](https://api-docs.statushub.com/api-v3-openapi/subscriber-subscription/createsubscribersubscription.md): Creates a new Subscription for existing Subscriber. Besides regular validation - like address correctness - there are a few additional constraints: - Address has to be unique for current Hub, - Single Subscriber can't have multiple subscriptions with same method name. For example it's not allowed for one Subscriber to have for example two email subscriptions. ### List Subscriptions - [GET /hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions](https://api-docs.statushub.com/api-v3-openapi/subscriber-subscription/listsubscribersubscriptions.md): Filters and returns Subscriptions with basic info for existing Subscriber. ### Retrieve a Subscription - [GET /hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions/{subscription_id}](https://api-docs.statushub.com/api-v3-openapi/subscriber-subscription/getsubscribersubscription.md): Returns data about single Subscription. ### Update a Subscription - [PUT /hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions/{subscription_id}](https://api-docs.statushub.com/api-v3-openapi/subscriber-subscription/updatesubscribersubscription.md): Modifies existing Subscription. Only modified attributes may be passed in payload. All other attributes will remain unchanged. ### Delete a Subscription - [DELETE /hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions/{subscription_id}](https://api-docs.statushub.com/api-v3-openapi/subscriber-subscription/deletesubscribersubscription.md): Deletes Subscription record. Records are soft-deleted which means that such deleted record can still be viewed and potentially restored. If deleted Subscription is the last active subscription for Subscriber, Subscriber record is also deleted. ### Restore a Subscription - [PUT /hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions/{subscription_id}/restore](https://api-docs.statushub.com/api-v3-openapi/subscriber-subscription/restoresubscribersubscription.md): Restores deleted Subscription. May fail if restoring would result in record that is not valid, for example because subscription with that address already exists. Restoring depending on data may either: - Recreate the record as a new one with new ID, - Undelete the record preserving it ID.