{
"openapi": "3.0.0",
"info": {
"version": "3.0-R1",
"title": "StatusHub Management API",
"termsOfService": "https://statushub.com/terms/",
"contact": {
"name": "StatusHub Support",
"email": "support@statushub.dev",
"url": "https://statushub.com/contact/"
},
"description": "# The StatusHub Management API v3\n\nStatusHub Management API V3 is a REST API intended to be an alternative\nto StatusHub Control Panel web interface.
\nExample use cases:\n- Automation of incidents creation and update,\n- Automation of Hub services management,\n- Automation of creation and deletion of Connected Hubs.\n\n## Previous API versions\n\nStatusHub Management API V3 replaces the Management API V2 which is now\ndeprecated.
\nManagement API V2 documentation has been moved to a new address:
\n[https://api-v2-docs.statushub.com](https://api-v2-docs.statushub.com)\n\n## StatusHub regions and API URL\n\nAll API requests should be made on hostname used to sign in to StatusHub\nControl Panel.
\nFor example if team members sign in to account on:
\n`https://company.app.statushub.io`
\nthen API requests should be made with following prefix:
\n`https://company.app.statushub.io/api/v3`\n\n#### EU region\n\nSame rule follows for customers using EU region and then\nthe example would be:
\nIf team members sign in to account on:
\n`https://company.app-eu1.statushub.io`
\nthen API requests should be made with following prefix:
\n`https://company.app-eu1.statushub.io/api/v3`\n\n## Rate limiting\n\nStatusHub API has two rate limits:\n\n- GET requests - 30 requests per second\n- All other requests - 5 requests per second\n\nRate limit is bound to the API Key used for authentication.
\nWhen the rate limit is exceeded, StatusHub API will respond with:\n\n - 429 response code\n - `{\"error\":\"Too many requests - please retry later\"}` response\n - Retry-After response header\n\nIn special cases, certain API methods may have different rate limits which will be mentioned in the API method description.\n\n## Time zones\n\nAll date/time parameters should be passed in UTC timezone\nregardless of the default Hub timezone settings.\n\n## Filtering events by time range\n\nEvents like Incident or Maintenance events can be filtered by time\nrange.
\nThere are two optional parameters in INDEX endpoints:\n- `start_time`,\n- `end_time`.\n\nFiltering logic is returning those events which period of occurrence\noverlaps with `start_time` and `end_time` range.
\nAlso, providing just one of range params, still uses the range but with\na default value of not provided one:\n- Providing just `start_time` assumes `end_time` as far in the future,\n- Providing just `end_time` assumes `start_time` as far in the past.\n- Not providing `start_time` nor `end_time` results in `start_time` being\n far in the past and `end_time` being far in the future and as a result\n all events are returned by time range filter.\n\nBelow are few examples to better understand the logic:\n\n**Maintenance example**\n\nLet's assume maintenance that started on 2025-02-01 and finished\non 2025-02-08.\n\nUsing `start_time=2025-01-01T00:00:00Z` and `end_time=2025-02-02T00:00:00Z`\nwill return the event because there is an overlap of both ranges:
\n<2025-01-01 00:00:00 UTC, 2025-02-02 00:00:00 UTC> and
\n<2025-02-01 00:00:00 UTC, 2025-02-08 00:00:00 UTC> overlap in
\n<2025-02-01 00:00:00 UTC, 2025-02-02 00:00:00 UTC>.\n\n**Open incident example**\n\nLet's assume incident that started on 2025-02-01 and hasn't been\nresolved.
\n\nUsing `start_time=2025-03-01T00:00:00Z` and not providing end time\nwill return the event because there is an overlap of both ranges:
\n<2025-02-01 00:00:00 UTC, far in the future due to incident still being open>\nand
\n<2025-03-01 00:00:00 UTC, far in the future due to not providing `end_time`>\noverlap in
\n<2025-03-01 00:00:00 UTC, far in the future>.\n\n## Extended properties\n\nStatusHub API V3 supports extended versions of certain response properties.\nBy default less frequently required fields are returned in basic form\nwith most common properties but if more information is needed `extend`\nquery parameter can be used.
\nCurrently StatusHub API V3 supports extending:\n- Incident flags,\n- Incident Update flags,\n- Maintenance event flags,\n- Subscription flags.\n
\n
\nExample for Maintenance flags:\n- Request path with basic flags: `/api/v3/hubs/hub-subdomain/maintenances`,\n- Request path with extended flags:\n `/api/v3/hubs/hub-subdomain/maintenances?extend=flags`\n"
},
"servers": [
{
"url": "https://{accountSubdomain}.app.statushub.io/api/v3",
"description": "Main US region",
"variables": {
"accountSubdomain": {
"default": "subdomain-of-your-account",
"description": "Unique subdomain of your account"
}
}
},
{
"url": "https://{accountSubdomain}.app-eu1.statushub.io/api/v3",
"description": "EU region",
"variables": {
"accountSubdomain": {
"default": "subdomain-of-your-account",
"description": "Unique subdomain of your account"
}
}
}
],
"security": [
{
"ApiKeyAuth": []
}
],
"tags": [
{
"name": "Incident",
"description": "Incident is a most important event type.
\nIncident represents an event that:\n- Started in the past,\n- Have updates which can be added while incident is being handled,\n- During creation and during its duration the total duration or end\n of the incident is not known,\n- Is resolved when `resolved` Incident Update is created\n for this incident,\n- Have non-0 duration. This means that Incident can't be created\n with `resolved` incident type.\n\nMost typical use case:\n- Hub Page list various customer-facing services,\n- When one of the services has an outage, Incident is created manually\n or through automation,\n- While team is working on restoring the service Incident Update entries\n are added manually or through automation to this incident to let\n customers know what's happening,\n- Once issue is resolved, Incident Update with `monitoring` incident type\n is being created while team is keeping an eye on service health,\n- Once situation is stable, Incident Update with `resolved` incident type\n is being created which ends the Incident.\n"
},
{
"name": "Incident Update",
"description": "Incident Update represents single update for Incident.
\nEvery Incident consists of at least one Incident Update and a resolved\nincident consists of at least two Incident Updates where the second\none has `resolved` incident type.\n"
},
{
"name": "Maintenance",
"description": "Maintenance represents an event that:\n- Has known start time which is typically in future - planned maintenance,\n- Has known end time during the moment of creation,\n- Is a single message.\n\nMost typical use case:\n- Hub Page list various customer-facing services,\n- One of the service will undergo a maintenance that will take it offline\n for duration of the maintenance,\n- Ahead of time, Maintenance event is created to let customers know\n that service will not be available during the specific time frame.\n"
},
{
"name": "Incident Update Template",
"description": "Incident Update Template is used to create Incident Updates in\nStatusHub Control Panel quicker.
\nIt can contain predefined:\n - title,\n - body,\n - incident type,\n - service statuses.\n"
},
{
"name": "Maintenance Template",
"description": "Maintenance Template is used to create Maintenance event in\nStatusHub Control Panel quicker.
\nIt can contain predefined:\n - title,\n - body,\n - duration,\n - service statuses.\n"
},
{
"name": "Platform Alert",
"description": "Platform Alert is a state of Hub which typically represent major event\naffecting whole product as opposed to Incident or Maintenance which\naffects specific services.
\nPlatform Alert is not connected with any service and therefore\nnotifications about Platform Alert are sent to all subscriptions\nregardless of their service selection.\n"
},
{
"name": "Hub",
"description": "Hub is a central record that represents the status page and holds\nall related records.\n"
},
{
"name": "Hub Privacy",
"description": "Allows managing various methods limiting access to a Hub Page.
\n\nUser-based methods - only one can be active in the same time:\n- SAML 2.0 - Recommended method offering the most flexibility\n and security,\n- Google OAuth - Use email address domain of user Google Account to\n limit the access to only those domains which are whitelisted.
\n Very easy to setup for companies using Google services,\n- Hub Password - Most basic method which use a single password\n that can be used by anyone in order to see the Hub Page.\n\nNetwork-based methods:\n- IP whitelist - Allow to specify a whitelist of IP V4 addresses and\n IP V4 ranges from which users are allowed to access the Hub Page.\n"
},
{
"name": "Assets",
"description": "Asset is a generic record that typically represents binary data\nlike image that can be referenced and used in other records.
\nFor example a Hub logo or favicon.\n"
},
{
"name": "Group",
"description": "Group purpose is to group Services in logical groups.\n"
},
{
"name": "Service",
"description": "Service represents fundamental Hub entity. Incident and Maintenance events\nare always attached to at least one Service. Service status should\nrepresent the health of the actual real-life entity it represents.\n"
},
{
"name": "Service Integration",
"description": "Service Integration allows creation automation that creates events\nin StatusHub from various 3rd party applications.
\nAs opposed to StatusHub Management API, those integrations endpoints\nare simplified and doesn't allow reading any data.
\nMost of integrations use per-service token for authorization.\n"
},
{
"name": "Connected Group",
"description": "Connected Group is a special representation of actual Group that through\nits Services is attached to Connected Hub.\n"
},
{
"name": "Connected Service",
"description": "Connected Service is a special representation of actual Service that\nis attached to Connected Hub.\n"
},
{
"name": "External Application",
"description": "Allows managing StatusHub widgets.\nCurrently supported applications are:\n- Minimal Widget - Small and basic version of StatusHub widget\n intended to be used in places requiring small visual size of the widget,\n- Widget - Default Statushub widget,\n- Zendesk - StatusHub App for Zendesk -\n [Zendesk Marketplace link](https://www.zendesk.com/marketplace/apps/support/127482/statushub/)\n"
},
{
"name": "Uptime",
"description": "Returns uptime information about:\n- Hub with either one value or per-day granularity,\n- Single group,\n- Single service.\n\nUptime is calculated according to following rules:\n- UTC timezone is used,\n- 'degraded-performance' is not counted towards downtime. Only 'down'\n status is treated as time when service was down,\n- If multiple events affect service in the same time, always worst\n status is being used for uptime calculation,\n- For group uptime, combination of worst statuses of all services\n in that group is used.\n For example, if group has three services and:\n - One was up for the whole time,\n - Second was down for the whole first half of the period (50%),\n - Last service was down for the second half of the period (50%),\n then group uptime is 0% because there was no time when none of its\n services were down.\n- For Hub uptime, combination of worst statuses of all services of that\n Hub is being used.\n"
},
{
"name": "Subscriber",
"description": "Subscriber represents a consumer of StatusHub notifications that\ncan have multiple subscriptions.
\nThose endpoints are typically used in one of two situations:\n- User is interested in subscriptions only for specific person or entity\n instead of seeing or managing subscriptions for the whole Hub,\n- SAML Hub protection method is being used. This results in subscriber\n record containing SAML NameID value in `idp_id` field.\n"
},
{
"name": "Subscriber Subscription",
"description": "Equivalent of Subscription endpoints but with scope limited to single\nSubscriber record which `id` is provided in request path.\n"
},
{
"name": "Subscription",
"description": "Individual subscription. It's a unique combination of:\n- Address,\n- Subscription method,\n- Hub.\n\nEvents created on a Hub Page depending on configuration will be sent\nto subscriptions of that Hub.
\nSubscription can be created for only a subset of Hub services which\nwill result in not receiving notifications about events affecting\nservices that were not selected.\n\nIn order to create or manage multiple subscriptions that should be\nassociated with the same person or entity, it's recommended to use\nSubscriber and Subscriber Subscription endpoints.\n"
}
],
"paths": {
"/hubs": {
"get": {
"tags": [
"Hub"
],
"summary": "List of Hubs",
"description": "Filters and returns Hub records with basic info.\n",
"parameters": [
{
"name": "type",
"in": "query",
"description": "Filters Hubs by their type.\n\nPossible values:\n * `type=primary` - return only Primary Hubs,\n * `type=connected` - return only Connected Hubs.\n\nHub types:\n * Primary Hub - Independent Hub without any overlap with other\n Hubs data.
\n Associated with billing subscription.\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"schema": {
"type": "string",
"enum": [
"primary",
"connected"
],
"default": "primary"
}
},
{
"name": "parent_id",
"in": "query",
"description": "Valid only for Connected Hubs.
\nFilters Hubs by their Primary Hub ID.\n",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "String that filters Hubs to those containing the search string in:\n- `name`,\n- `subdomain`.\n",
"schema": {
"type": "string"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"start_time"
],
"default": "position"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "per_parent_sort",
"in": "query",
"description": "Valid only for Connected Hubs.
\n* `true` - sorts Connected Hubs by their parent Primary Hub position,\n* `false` - omits sorting Connected Hubs by their parent Primary Hub\n position.\n",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 1
},
"name": {
"type": "string",
"description": "Name of the Hub.",
"example": "Example Hub"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"No access to any of Hubs": {
"description": "Returned when Member does not have access to even one Hub inside current account.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid type param": {
"description": "Returned when `type` param is invalid.\n",
"value": {
"type": [
"must be one of: primary, connected"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}": {
"get": {
"tags": [
"Hub"
],
"summary": "Show Hub",
"description": "Returns data about single Hub.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 3
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub"
],
"summary": "Update hub",
"description": "Modifies basic settings of an existing Hub. Only modified attributes may be passed in payload. All other attributes will remain unchanged.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 3
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid maintenance_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong product_url format": {
"description": "Returned when `product_url` does not have a valid URL format.\nFor example when it doesn't have protocol (`https://`) specified.\n",
"value": {
"product_url": [
"invalid format"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/status/counters": {
"get": {
"tags": [
"Hub"
],
"summary": "Hub services conditions overview",
"description": "Returns Hub services conditions overview",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"maxProperties": 3,
"properties": {
"up": {
"type": "integer",
"example": 0
},
"degraded-performance": {
"type": "integer",
"example": 4
},
"down": {
"type": "integer",
"example": 1
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/status/services/{service_id}": {
"get": {
"operationId": "listServiceStatuses",
"tags": [
"ServiceStatus"
],
"summary": "Show service statuses",
"description": "Returns a list of all services statuses",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 4
},
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 5
},
"service_name": {
"type": "string"
},
"service_status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"maintenance_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 6
}
},
"incident_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 7
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/connected_hubs": {
"get": {
"tags": [
"Hub"
],
"summary": "List of Connected Hubs",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of Primary Hub for requested Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "q",
"in": "query",
"description": "Query string",
"schema": {
"type": "string"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"start_time"
],
"default": "position"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 8
},
"name": {
"type": "string",
"description": "Name of the Hub.",
"example": "Example Hub"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"parent_id": {
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Contains the numerical ID of Primary Hub for current Connected Hub.
\n"
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
},
"Invalid sort_prop param": {
"description": "Returned when `sort_prop` param is invalid.\n",
"value": {
"sort_prop": [
"must be one of: position, created_at, updated_at"
]
}
}
}
}
}
}
}
},
"post": {
"tags": [
"Hub"
],
"summary": "Create a new Connected Hub",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of Primary Hub for requested Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 12
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid or not available subdomain": {
"description": "Returned when `subdomain` is invalid or not available.\n",
"value": {
"subdomain": [
"already taken",
"not allowed"
]
}
},
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
},
"Quota has been reached": {
"description": "Returned when the Connected Hubs quota for current Primary\nHub has been reached or Connected Hubs are not available\nfor current Primary Hub plan.\n",
"value": {
"connected_hub": [
"limit reached"
]
}
},
"Wrong product_url format": {
"description": "Returned when `product_url` does not have a valid URL format.\nFor example when it doesn't have protocol (`https://`) specified.\n",
"value": {
"product_url": [
"invalid format"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/connected_hubs/{connected_subdomain}": {
"get": {
"tags": [
"Hub"
],
"summary": "Show Connected Hub",
"description": "Returns data about single Connected Hub.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of Primary Hub for requested Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "connected_subdomain",
"in": "path",
"description": "Unique `subdomain` of Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 12
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub"
],
"summary": "Update Connected Hub",
"description": "Modifies basic settings of an existing Connected Hub. Only modified attributes may be passed in payload. All other attributes will remain unchanged.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of Primary Hub for requested Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "connected_subdomain",
"in": "path",
"description": "Unique `subdomain` of Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 12
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid maintenance_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong product_url format": {
"description": "Returned when `product_url` does not have a valid URL format.\nFor example when it doesn't have protocol (`https://`) specified.\n",
"value": {
"product_url": [
"invalid format"
]
}
}
}
}
}
}
}
},
"delete": {
"tags": [
"Hub"
],
"summary": "Delete a Connected Hub",
"description": "Deletes Connected Hub record.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of Primary Hub for requested Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "connected_subdomain",
"in": "path",
"description": "Unique `subdomain` of Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/connected_hubs/{connected_subdomain}/copy": {
"post": {
"tags": [
"Hub"
],
"summary": "Copy Connected Hub",
"description": "Creates a new Connected Hub with same settings as existing Connected Hub.\nCopying will preserve all configuration options which includes:\n- Hub properties (excluding custom domain)\n- Privacy settings\n- List of associated services and groups\n- Appearance settings\n- Notification settings\n- Features enabled by StatusHub support\n\nCopy will **not** copy events nor subscribers data.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of Primary Hub for requested Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "connected_subdomain",
"in": "path",
"description": "Unique `subdomain` of Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 12
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid or not available subdomain": {
"description": "Returned when `subdomain` is invalid or not available.\n",
"value": {
"subdomain": [
"already taken",
"not allowed"
]
}
},
"Quota has been reached": {
"description": "Returned when the Connected Hubs quota for current Primary\nHub has been reached or Connected Hubs are not available\nfor current Primary Hub plan.\n",
"value": {
"connected_hub": [
"limit reached"
]
}
},
"Wrong product_url format": {
"description": "Returned when `product_url` does not have a valid URL format.\nFor example when it doesn't have protocol (`https://`) specified.\n",
"value": {
"product_url": [
"invalid format"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/access_restriction": {
"get": {
"tags": [
"Hub Privacy"
],
"summary": "Retrieve Hub privacy state",
"description": "Lists all available methods for restricting access to the Hub as well as\nthe currently enabled access restriction method or `public`\nif Hub is public.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"allowed_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"saml",
"google_oauth",
"global_password",
"public"
]
},
"example": [
"saml",
"google_oauth",
"global_password",
"public"
]
},
"enabled_method": {
"type": "string",
"enum": [
"saml",
"google_oauth",
"global_password",
"public"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/access_restriction/saml": {
"get": {
"tags": [
"Hub Privacy"
],
"summary": "Retrieve SAML settings",
"description": "Returns data about SAML authentication.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
},
"idp_metadata": {
"type": "string",
"nullable": true,
"description": "IdP SAML metadata in XML format.\n",
"example": "\n\n...\n\n"
},
"debug": {
"type": "boolean",
"description": "Controls verbosity of SAML error page:\n- `true` - Show detailed error message,\n- `false` - Show generic error message without details.\n"
},
"sign_out_target": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Location where user will be redirected after successful sign-out.\n"
},
"slo": {
"type": "boolean",
"description": "Controls if SLO should be used when signing-out from Hub:\n- `true` - SLO is enabled. This requires `SingleLogoutService`\nconfiguration to be included in `idp_metadata`,\n- `false` - SLO is not enabled.\n"
},
"sp_data": {
"type": "object",
"additionalProperties": false,
"description": "Informational field.
\nReturns identifiers and URL that can be used to setup SAML connection.\n",
"required": [],
"properties": {
"certificate_url": {
"description": "URL from which StatusHub SAML public certificate can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"metadata_url": {
"description": "URL from which StatusHub SP metadata in XML format can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"entity_id": {
"description": "SP Entity ID.",
"type": "string",
"format": "uri"
},
"sso_url": {
"description": "Sign-on URL.",
"type": "string",
"format": "uri"
},
"slo_url": {
"description": "Sign-out URL. Works only if `slo` is enabled.",
"type": "string",
"format": "uri"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub Privacy"
],
"summary": "Update SAML authentication settings",
"description": "Modifies SAML authentication settings.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"idp_metadata": {
"type": "string",
"nullable": true,
"description": "IdP SAML metadata in XML format.\n",
"example": "\n\n...\n\n"
},
"slo": {
"type": "boolean",
"description": "Controls if SLO should be used when signing-out from Hub:\n- `true` - SLO is enabled. This requires `SingleLogoutService`\nconfiguration to be included in `idp_metadata`,\n- `false` - SLO is not enabled.\n"
},
"debug": {
"nullable": true,
"type": "boolean",
"description": "Controls verbosity of SAML error page:\n- `true` - Show detailed error message,\n- `false` - Show generic error message without details.\n"
},
"sign_out_target": {
"nullable": true,
"type": "string",
"format": "uri",
"description": "Location where user will be redirected after successful sign-out.\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
},
"idp_metadata": {
"type": "string",
"nullable": true,
"description": "IdP SAML metadata in XML format.\n",
"example": "\n\n...\n\n"
},
"debug": {
"type": "boolean",
"description": "Controls verbosity of SAML error page:\n- `true` - Show detailed error message,\n- `false` - Show generic error message without details.\n"
},
"sign_out_target": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Location where user will be redirected after successful sign-out.\n"
},
"slo": {
"type": "boolean",
"description": "Controls if SLO should be used when signing-out from Hub:\n- `true` - SLO is enabled. This requires `SingleLogoutService`\nconfiguration to be included in `idp_metadata`,\n- `false` - SLO is not enabled.\n"
},
"sp_data": {
"type": "object",
"additionalProperties": false,
"description": "Informational field.
\nReturns identifiers and URL that can be used to setup SAML connection.\n",
"required": [],
"properties": {
"certificate_url": {
"description": "URL from which StatusHub SAML public certificate can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"metadata_url": {
"description": "URL from which StatusHub SP metadata in XML format can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"entity_id": {
"description": "SP Entity ID.",
"type": "string",
"format": "uri"
},
"sso_url": {
"description": "Sign-on URL.",
"type": "string",
"format": "uri"
},
"slo_url": {
"description": "Sign-out URL. Works only if `slo` is enabled.",
"type": "string",
"format": "uri"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"IdP metadata not compatible with SLO": {
"description": "Returned when trying to enable SLO while using IdP metadata that doesn't support SLO.
For example due to missing `SingleLgoutService`.\n",
"value": {
"idp_metadata": [
"must contain the SLO target URL"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/access_restriction/google_oauth": {
"get": {
"tags": [
"Hub Privacy"
],
"summary": "Retrieve Google OAuth settings",
"description": "Returns data about Google OAuth authorization.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "State of Google OAuth authorization.
In order to enable this method the domains whitelist has to be set and enabled.\n"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub Privacy"
],
"summary": "Update Google OAuth authorization settings",
"description": "Modifies Google OAuth authorization settings.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean",
"description": "State of Google OAuth authorization.
In order to enable this method the domains whitelist has to be set and enabled.\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "State of Google OAuth authorization.
In order to enable this method the domains whitelist has to be set and enabled.\n"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Domains whitelist not set": {
"description": "Returned when trying to enable Google OAuth without having domains whitelist enabled.\n",
"value": {
"domains_whitelist_enabled": [
"selected protection method requires enabled domains whitelist"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/access_restriction/global_password": {
"get": {
"tags": [
"Hub Privacy"
],
"summary": "Retrieve Hub password settings",
"description": "Returns data about Hub password.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub Privacy"
],
"summary": "Update Hub password settings",
"description": "Modifies Hub password settings.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"password": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Too short password": {
"description": "Returned when trying to enable password protection with too short password.\n",
"value": {
"password": [
"length must be within 8 - 255"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/access_restriction/domains_whitelist": {
"get": {
"tags": [
"Hub Privacy"
],
"summary": "Retrieve domain-based restriction details",
"description": "Returns data about domain-based restriction for Hub access restriction\nmethods providing authentication of user with user email.
\nApplies to:\n- SAML - optional,\n- Google OAuth - required.\n\nOnce set if visitor trying to sign-in has a domain reported by\nauthentication method not matching any of the domains in domains whitelist,\nthe access to Hub is not granted even if authentication method normally\nwould grant access to this visitor.\n\nRequired to be enabled when using Google OAuth restriction method.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
},
"domains_whitelist": {
"type": "array",
"items": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]\\.[a-z]{2,}"
},
"description": "Array of domain names.\n",
"example": [
"company.com",
"another-domain.com"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub Privacy"
],
"summary": "Update Hub domain-based restrictions",
"description": "Modified the domain-based restrictions settings.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"domains_whitelist": {
"type": "array",
"items": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]\\.[a-z]{2,}"
},
"description": "Array of domain names.\n",
"example": [
"company.com",
"another-domain.com"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
},
"domains_whitelist": {
"type": "array",
"items": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]\\.[a-z]{2,}"
},
"description": "Array of domain names.\n",
"example": [
"company.com",
"another-domain.com"
]
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Google OAuth is enabled": {
"description": "Returned when trying to disable domains whitelist while Google OAuth is an active access restriction method for current Hub.\n",
"value": {
"enabled": [
"can not be disabled because selected protection method requires enabled domains whitelist"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/access_restriction/ip_whitelist": {
"get": {
"tags": [
"Hub Privacy"
],
"summary": "Retrieve ip-based restriction details",
"description": "Returns data about ip-based restriction for Hub.
\nIf enabled only visitors from whitelisted IP addresser or IP ranges\nare allowed to access the Hub. All other visitors will see 404 error.
\nSupported address formats:\n- IP V4 address,\n- IP V4 range in CIDR notation.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
},
"ip_whitelist": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}",
"description": "IP V4 address"
},
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\/[0-9]{1,2}",
"description": "IP V4 range in CIDR format\n"
}
]
},
"example": [
"54.210.121.161",
"144.201.96.0/21"
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub Privacy"
],
"summary": "Update Hub ip-based restrictions",
"description": "Modified the ip-based restrictions settings.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"ip_whitelist": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}",
"description": "IP V4 address"
},
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\/[0-9]{1,2}",
"description": "IP V4 range in CIDR format\n"
}
]
},
"example": [
"54.210.121.161",
"144.201.96.0/21"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean"
},
"ip_whitelist": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}",
"description": "IP V4 address"
},
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\/[0-9]{1,2}",
"description": "IP V4 range in CIDR format\n"
}
]
},
"example": [
"54.210.121.161",
"144.201.96.0/21"
]
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid address format": {
"description": "Returned when trying to use IP address in format other than IP V4 or IP V4 CIDR.\n",
"value": {
"ip_whitelist": [
"provided IP(s) address(es) is(are) in an invalid format"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/appearance": {
"get": {
"tags": [
"Hub"
],
"summary": "Show Hub appearance settings",
"description": "Returns data about Hub appearance settings.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"description": {
"type": "string",
"nullable": true,
"description": "Optional description than can be visible on Hub Page.
May contain basic HTML tags.\n"
},
"favicon_url": {
"description": "URL of Hub favicon image.",
"type": "string",
"format": "uri",
"nullable": true
},
"logo_url": {
"description": "URL of Hub logo image.",
"type": "string",
"format": "uri",
"nullable": true
},
"navbar_item": {
"type": "object",
"description": "Allows to add button with link to Hub Page navbar.
Both label and URL are mandatory if any of those fields contains value.\n",
"additionalProperties": false,
"properties": {
"label": {
"type": "string",
"nullable": true,
"example": "Support portal"
},
"url": {
"example": "https://help.example-company.com",
"type": "string",
"format": "uri",
"nullable": true
}
}
},
"status_names": {
"type": "object",
"additionalProperties": false,
"description": "Custom labels used on Hub Page legend section.
Can be used to change default values to better match Hub Page use-case.
For example if Hub Page is set to show availability of meeting rooms then 'down' may mean 'Room is not available' and 'degraded-performance' may mean 'Room is booked'.\n",
"properties": {
"up": {
"type": "string",
"default": "Service is operating normally"
},
"degraded-performance": {
"type": "string",
"default": "Performance issues"
},
"down": {
"type": "string",
"default": "Service disruption"
}
}
},
"localization": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"iso_week": {
"type": "boolean",
"description": "Use ISO week numbering system:\n * true - week starts on Monday,\n * false - week starts on Sunday.\n"
},
"date_format": {
"type": "string",
"enum": [
"EU",
"US"
],
"description": "Used date format:\n * EU - dd/mm/yyyy\n * US - mm/dd/yyyy\n"
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
],
"description": "Used time format:\n * 12h - hh:mm AM/PM,\n * 24h - HH:mm.\n"
},
"time_zone_name": {
"type": "string",
"description": "Default time zone used for Hub Page for visitors who haven't chosen different time zone.\n"
}
}
},
"layout": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"view_type": {
"type": "string",
"enum": [
"list",
"calendar",
"no_history",
"connected_hubs_grid"
],
"description": "History view type\n"
},
"background_color": {
"nullable": true,
"type": "string",
"description": "Custom background color in Hex format.
For Hubs still using background image, setting `background_color` will remove the background image which can then only be added through a support request.\n",
"example": "#ffffff"
},
"platform_alerts": {
"type": "boolean",
"description": "Show platform alerts on this Hub Page"
},
"hubs_switcher": {
"type": "boolean",
"description": "Show Hubs switcher on this Hub Page.
This setting controls if the Hub Switcher is visible on current Hub Page.
In order to choose which Hubs are visible in Hub Switcher `show_in_hubs_switcher` should be used on respective Hubs.\n"
},
"show_in_hubs_switcher": {
"type": "boolean",
"description": "Show this Hub inside Hubs Switcher in Hubs that show the Hubs Switcher in current account.\n"
},
"uptime_chart": {
"type": "boolean",
"description": "Shows uptime chart on hits Hub Page."
},
"whitelabel": {
"type": "boolean",
"description": "Hide default \"Powered by StatusHub\" footer.\n"
},
"background_image_url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "URL of image used as Hub background image.
This is a read-only field and is a legacy feature.
Once `background_color` is set, it's not possible to set the `background_image` nor `background_image_url` again in API nor in StatusHub Control Panel. Only way to set the background image is through a support request.
This field is not returned when background image is not being used.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"tags": [
"Hub"
],
"summary": "Update Hub appearance settings",
"description": "Modifies an existing Hub appearance settings. Only modified attributes may be passed in payload. All other attributes will remain unchanged.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"description": {
"type": "string",
"nullable": true,
"description": "Optional description than can be visible on Hub Page.
May contain basic HTML tags.\n"
},
"navbar_item": {
"type": "object",
"description": "Allows to add button with link to Hub Page navbar.
Both label and URL are mandatory if any of those fields contains value.\n",
"additionalProperties": false,
"properties": {
"label": {
"type": "string",
"nullable": true,
"example": "Support portal"
},
"url": {
"example": "https://help.example-company.com",
"type": "string",
"format": "uri",
"nullable": true
}
}
},
"status_names": {
"type": "object",
"additionalProperties": false,
"description": "Custom labels used on Hub Page legend section.
Can be used to change default values to better match Hub Page use-case.
For example if Hub Page is set to show availability of meeting rooms then 'down' may mean 'Room is not available' and 'degraded-performance' may mean 'Room is booked'.\n",
"properties": {
"up": {
"type": "string",
"default": "Service is operating normally"
},
"degraded-performance": {
"type": "string",
"default": "Performance issues"
},
"down": {
"type": "string",
"default": "Service disruption"
}
}
},
"localization": {
"type": "object",
"additionalProperties": false,
"properties": {
"iso_week": {
"type": "boolean",
"description": "Use ISO week numbering system:\n * true - week starts on Monday,\n * false - week starts on Sunday.\n"
},
"date_format": {
"type": "string",
"enum": [
"EU",
"US"
],
"description": "Used date format:\n * EU - dd/mm/yyyy\n * US - mm/dd/yyyy\n"
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
],
"description": "Used time format:\n * 12h - hh:mm AM/PM,\n * 24h - HH:mm.\n"
},
"time_zone_name": {
"type": "string",
"description": "Default time zone used for Hub Page for visitors who haven't chosen different time zone.\n"
}
}
},
"layout": {
"type": "object",
"additionalProperties": false,
"properties": {
"view_type": {
"type": "string",
"enum": [
"list",
"calendar",
"no_history",
"connected_hubs_grid"
],
"description": "History view type\n"
},
"background_color": {
"type": "string",
"description": "Custom background color in Hex format.
For Hubs still using background image, setting `background_color` will remove the background image which can then only be added through a support request.\n",
"example": "#ffffff"
},
"platform_alerts": {
"type": "boolean",
"description": "Show platform alerts on this Hub Page"
},
"hubs_switcher": {
"type": "boolean",
"description": "Show Hubs switcher on this Hub Page.
This setting controls if the Hub Switcher is visible on current Hub Page.
In order to choose which Hubs are visible in Hub Switcher `show_in_hubs_switcher` should be used on respective Hubs.\n"
},
"show_in_hubs_switcher": {
"type": "boolean",
"description": "Show this Hub inside Hubs Switcher in Hubs that show the Hubs Switcher in current account.\n"
},
"uptime_chart": {
"type": "boolean",
"description": "Shows uptime chart on hits Hub Page."
},
"whitelabel": {
"type": "boolean",
"description": "Hide default \"Powered by StatusHub\" footer.\n"
}
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"description": {
"type": "string",
"nullable": true,
"description": "Optional description than can be visible on Hub Page.
May contain basic HTML tags.\n"
},
"favicon_url": {
"description": "URL of Hub favicon image.",
"type": "string",
"format": "uri",
"nullable": true
},
"logo_url": {
"description": "URL of Hub logo image.",
"type": "string",
"format": "uri",
"nullable": true
},
"navbar_item": {
"type": "object",
"description": "Allows to add button with link to Hub Page navbar.
Both label and URL are mandatory if any of those fields contains value.\n",
"additionalProperties": false,
"properties": {
"label": {
"type": "string",
"nullable": true,
"example": "Support portal"
},
"url": {
"example": "https://help.example-company.com",
"type": "string",
"format": "uri",
"nullable": true
}
}
},
"status_names": {
"type": "object",
"additionalProperties": false,
"description": "Custom labels used on Hub Page legend section.
Can be used to change default values to better match Hub Page use-case.
For example if Hub Page is set to show availability of meeting rooms then 'down' may mean 'Room is not available' and 'degraded-performance' may mean 'Room is booked'.\n",
"properties": {
"up": {
"type": "string",
"default": "Service is operating normally"
},
"degraded-performance": {
"type": "string",
"default": "Performance issues"
},
"down": {
"type": "string",
"default": "Service disruption"
}
}
},
"localization": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"iso_week": {
"type": "boolean",
"description": "Use ISO week numbering system:\n * true - week starts on Monday,\n * false - week starts on Sunday.\n"
},
"date_format": {
"type": "string",
"enum": [
"EU",
"US"
],
"description": "Used date format:\n * EU - dd/mm/yyyy\n * US - mm/dd/yyyy\n"
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
],
"description": "Used time format:\n * 12h - hh:mm AM/PM,\n * 24h - HH:mm.\n"
},
"time_zone_name": {
"type": "string",
"description": "Default time zone used for Hub Page for visitors who haven't chosen different time zone.\n"
}
}
},
"layout": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"view_type": {
"type": "string",
"enum": [
"list",
"calendar",
"no_history",
"connected_hubs_grid"
],
"description": "History view type\n"
},
"background_color": {
"nullable": true,
"type": "string",
"description": "Custom background color in Hex format.
For Hubs still using background image, setting `background_color` will remove the background image which can then only be added through a support request.\n",
"example": "#ffffff"
},
"platform_alerts": {
"type": "boolean",
"description": "Show platform alerts on this Hub Page"
},
"hubs_switcher": {
"type": "boolean",
"description": "Show Hubs switcher on this Hub Page.
This setting controls if the Hub Switcher is visible on current Hub Page.
In order to choose which Hubs are visible in Hub Switcher `show_in_hubs_switcher` should be used on respective Hubs.\n"
},
"show_in_hubs_switcher": {
"type": "boolean",
"description": "Show this Hub inside Hubs Switcher in Hubs that show the Hubs Switcher in current account.\n"
},
"uptime_chart": {
"type": "boolean",
"description": "Shows uptime chart on hits Hub Page."
},
"whitelabel": {
"type": "boolean",
"description": "Hide default \"Powered by StatusHub\" footer.\n"
},
"background_image_url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "URL of image used as Hub background image.
This is a read-only field and is a legacy feature.
Once `background_color` is set, it's not possible to set the `background_image` nor `background_image_url` again in API nor in StatusHub Control Panel. Only way to set the background image is through a support request.
This field is not returned when background image is not being used.\n"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing navbar item url": {
"description": "Returned when setting just the `label` for `navbar_item`.\n",
"value": {
"navbar_item.url": [
"cant be blank"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/assets": {
"post": {
"tags": [
"Assets"
],
"summary": "Upload an asset",
"description": "Uploads an asset for existing Hub.\nCurrently supported assets are:\n- Logo,\n- Favicon.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"file"
],
"properties": {
"type": {
"type": "string",
"enum": [
"logo",
"favicon"
],
"description": "Type of asset to create"
},
"file": {
"type": "string",
"format": "binary",
"description": "File to upload as asset"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Asset created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid image type": {
"description": "Returned when uploading an asset file that has a wrong content type. For example is not an image for logo upload.\n",
"value": {
"file": [
"invalid content type"
]
}
},
"Not-square favicon image": {
"description": "Returned when uploading image that is not a square as a favicon.\n",
"value": {
"file": [
"image should be square"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/assets/{asset_id}": {
"delete": {
"tags": [
"Assets"
],
"summary": "Delete an asset",
"description": "Deletes an asset for current Hub. This method can be used to remove for example Logo from a Hub.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "asset_id",
"description": "Unique identifier for the asset.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"logo",
"favicon"
]
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/hubs/{subdomain}/platform_alert": {
"get": {
"tags": [
"Platform Alert"
],
"summary": "Show Platform Alert data",
"description": "Returns data about Platform Alert state.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"active": {
"type": "boolean"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"silent": {
"type": "boolean",
"description": "Send notification to subscribers"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"post": {
"tags": [
"Platform Alert"
],
"summary": "Set/Unset Platform Alert",
"description": "Sets Platform Alert state.
Can be used to both set/enable the Platform Alert as well as to unset/disable it.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"active",
"title",
"body",
"silent"
],
"properties": {
"active": {
"type": "boolean"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"silent": {
"type": "boolean",
"description": "Send notification to subscribers"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"active": {
"type": "boolean"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"silent": {
"type": "boolean",
"description": "Send notification to subscribers"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Empty body": {
"description": "Returned when trying to set Platform Alert without body message.\n",
"value": {
"body": [
"is missing"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/incidents": {
"post": {
"operationId": "createIncident",
"tags": [
"Incident"
],
"summary": "Create an Incident",
"description": "Creates a new Incident. During creation, first Incident Update for this Incident will also be created.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"start_time",
"incident_type",
"service_statuses"
],
"properties": {
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
},
"original_incident_id": {
"type": "integer",
"description": "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.\n",
"minimum": 1,
"example": 102
}
}
},
"examples": {
"Basic example": {
"description": "Basic example of creating incident affecting two services.\n",
"value": {
"title": "Example incident title",
"start_time": "2025-05-02 12:34:56",
"incident_type": "investigating",
"body": "Incident body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
]
}
},
"Creating an incident draft with silent option": {
"description": "Example of creating silent incident draft.
Please note that `silent` affects notification to subscribers and does not affect nor suppress draft notifications to team members.\n",
"value": {
"title": "Example incident title - silent + draft",
"start_time": "2025-05-02 12:34:56",
"incident_type": "investigating",
"body": "Incident body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
],
"silent": true,
"state": "draft"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 15
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"title": {
"type": "string",
"description": "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_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the `start_time` of the first (by `start_time`) Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end. If not set it means that the event has not ended yet.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
},
"follow_up": {
"type": "boolean",
"description": "Is it a follow-up incident."
},
"published": {
"type": "boolean",
"description": "Event was published on Hub Page."
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed incident. Unconfirmed incidents are still visible on Hub Page.\n"
}
}
}
]
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing required values": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"title": [
"is missing"
],
"start_time": [
"is missing"
],
"incident_type": [
"is missing"
]
}
},
"Start time in future": {
"description": "Returned when `start_time` is set in future. Incidents unlike Maintenance events, can't be created in future.\n",
"value": {
"start_time": [
"cannot_be_in_future"
]
}
},
"Wrong service IDs": {
"description": "Returned when `service_id` doesn't match any service in currently used Hub. Same error is returned when there is no service with such ID as well as when service with such ID exists but in different Hub.\n",
"value": {
"service_statuses": [
"wrong_hub"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listIncidents",
"tags": [
"Incident"
],
"summary": "List Incidents",
"description": "Filters and returns Incident records for current Hub with basic info.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "created_by_me",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
},
"description": "Behavior:\n* `true` - filter events to only those which were created by\ncurrent user,\n* `false` - filter events to only those which were **not**\ncreated by current user,\n* `all` - don't filter events by creator.\n"
},
{
"name": "draft",
"in": "query",
"description": "Filters events by presence of unpublished Incident Update:\n* `true` - return only events containing at least one unpublished (draft)\nIncident Update,\n* `false` - return only events without any unpublished Incident Updates,\n* `all` - return events without filtering by draft status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "incident_types",
"in": "query",
"description": "Comma-separated names of incident types.
\nFilters incidents by status of last (including draft) update.\nExamples:\n * `incident_types=monitoring`\n * `incident_types=investigating,identified`\n\nPossible incident type values:\n * `identified`,\n * `investigating`,\n * `monitoring`,\n * `resolved`.\n\nWhen not set, do not filter incidents by type of last update.\n",
"schema": {
"type": "string"
}
},
{
"name": "published",
"in": "query",
"description": "Filter events by status of publication on Hub Page:\n* `true` - return only events published on Hub Page,\n* `false` - return only events that were not published on Hub Page.\n* `all` - don't filter events by publication status.\n",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
}
},
{
"name": "unconfirmed",
"in": "query",
"description": "Filter events by state of the event:\n* `true` - return only events were published as unconfirmed on Hub Page,\n* `false` - return only events were published as confirmed on Hub Page.\n* `all` - don't filter events by unconfirmed status.\n",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
}
},
{
"name": "archived",
"in": "query",
"description": "Filters incidents by archived status:\n* `true` - return only incidents that were archived,\n* `false` - return only incidents that were not archived,\n* `all` - return incidents without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted",
"in": "query",
"description": "Filters incidents by deletion status:\n* `true` - return only incidents that were deleted,\n* `false` - return only incidents that were not deleted,\n* `all` - return incidents without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"created_at",
"start_time",
"updated_at"
],
"default": "start_time"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "period_name",
"in": "query",
"description": "Comma-separated period names.
\nFilters event by period name.\n\nExamples:\n * `period_name=current`\n * `period_name=past,current`\n\nPossible period name values:\n * `past`,\n * `current`.\n\nWhen not set, do not filter by period.\n",
"schema": {
"type": "string"
}
},
{
"name": "service_ids",
"in": "query",
"description": "Comma-separated string of service ids.\n\nFilters events by at least one affected service, specified in params.\n\nExample: `service_ids=1,2,3`\n",
"schema": {
"type": "string"
}
},
{
"name": "service_statuses",
"in": "query",
"description": "Comma-separated string of service statuses names.\n\nFilters events by at least one affected service with specified status.\n\nExamples:\n* `service_statuses=degraded-performance`\n* `service_statuses=up,down`\n\nPossible incident type values:\n* `up`\n* `degraded-performance`\n* `down`\n",
"schema": {
"type": "string"
}
},
{
"name": "start_time",
"in": "query",
"description": "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.\n",
"schema": {
"type": "string",
"default": "1900-01-01T00:00:00Z",
"format": "date-time"
}
},
{
"name": "end_time",
"in": "query",
"description": "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.\n",
"schema": {
"type": "string",
"default": "2199-01-01T00:00:00Z",
"format": "date-time"
}
},
{
"name": "q",
"in": "query",
"description": "String that filters events to those containing the search string in:\n- `title`,\n- `body`.\n",
"schema": {
"type": "string"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 13
},
"title": {
"type": "string",
"description": "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."
},
"last_incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the `start_time` of the first (by `start_time`) Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end. If not set it means that the event has not ended yet.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
},
"follow_up": {
"type": "boolean",
"description": "Is it a follow-up incident."
},
"published": {
"type": "boolean",
"description": "Event was published on Hub Page."
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed incident. Unconfirmed incidents are still visible on Hub Page.\n"
}
}
}
]
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid deleted param": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/incidents/{incident_id}": {
"get": {
"operationId": "getIncident",
"tags": [
"Incident"
],
"summary": "Retrieve an Incident",
"description": "Returns data about single Incident.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 15
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"title": {
"type": "string",
"description": "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_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the `start_time` of the first (by `start_time`) Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end. If not set it means that the event has not ended yet.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
},
"follow_up": {
"type": "boolean",
"description": "Is it a follow-up incident."
},
"published": {
"type": "boolean",
"description": "Event was published on Hub Page."
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed incident. Unconfirmed incidents are still visible on Hub Page.\n"
}
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteIncident",
"tags": [
"Incident"
],
"summary": "Delete an Incident",
"description": "Deletes Incident record. Records are soft-deleted which means that such deleted record can still be viewed or potentially restored.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/incidents/{incident_id}/incident_updates": {
"post": {
"operationId": "createIncidentIncidentUpdate",
"tags": [
"Incident Update"
],
"summary": "Create an Incident Update",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"start_time",
"incident_type"
],
"properties": {
"title": {
"type": "string",
"description": "Title of this update.
Can contain only plain text.
Setting `title` to value different from current title of Incident may result in changing of Incident title.
Incident title equals to title of latest (by `start_time`) published (not draft) Incident Update `title`.\n"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.
This parameter is required unless `incident_type` is `resolved`, in which case it is forbidden because resolving an incident automatically sets all affected services to `up` status for this incident.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
}
}
},
"examples": {
"Basic example": {
"description": "Basic example of creating incident update affecting two services.\n",
"value": {
"title": "Example incident title",
"start_time": "2025-05-02 12:34:56",
"incident_type": "investigating",
"body": "Incident body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
]
}
},
"Resolving incident": {
"description": "Resolving incident by creating incident update with `\"incident_type\": \"resolved\"`.\n",
"value": {
"title": "Example incident title",
"start_time": "2025-05-02 12:34:56",
"incident_type": "resolved",
"body": "Final message
with basic HTML tags."
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 25
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"title": {
"type": "string",
"description": "Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.\n"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamps of a Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed Incident Update. Unconfirmed can only be a first Incident Update of an Incident. Unconfirmed Incident Updates are still visible on Hub Page.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Incident Update.
Silent event does not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
}
}
}
]
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing required values": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"title": [
"is missing"
],
"start_time": [
"is missing"
],
"incident_type": [
"is missing"
]
}
},
"Start time in future": {
"description": "Returned when `start_time` is set in future. Incidents unlike Maintenance events, can't be created in future.\n",
"value": {
"start_time": [
"cannot_be_in_future"
]
}
},
"Wrong service IDs": {
"description": "Returned when `service_id` doesn't match any service in currently used Hub. Same error is returned when there is no service with such ID as well as when service with such ID exists but in different Hub.\n",
"value": {
"service_statuses": [
"wrong_hub"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listIncidentIncidentUpdates",
"tags": [
"Incident Update"
],
"summary": "List Incident Updates",
"description": "Filters and returns Incident Update records for specific Incident and current Hub with basic info.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "archived",
"in": "query",
"description": "Filters incident updates by archived status:\n* `true` - return only incident updates that were archived,\n* `false` - return only incident updates that were not archived,\n* `all` - return incident updates without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "q",
"in": "query",
"description": "String that filters events to those containing the search string in:\n- `title`,\n- `body`.\n",
"schema": {
"type": "string"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"start_time",
"created_at",
"updated_at"
],
"default": "start_time"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 16
},
"title": {
"type": "string",
"description": "Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.\n"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamps of a Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"state": {
"type": "string",
"enum": [
"undefined",
"draft",
"unconfirmed",
"published"
],
"description": "Event state",
"example": "published"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed Incident Update. Unconfirmed can only be a first Incident Update of an Incident. Unconfirmed Incident Updates are still visible on Hub Page.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Incident Update.
Silent event does not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
}
}
}
]
}
}
},
"maxItems": 10
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/incidents/{incident_id}/incident_updates/{incident_update_id}": {
"get": {
"operationId": "getIncidentIncidentUpdate",
"tags": [
"Incident Update"
],
"summary": "Retrieve an Incident Update",
"description": "Returns data about single Incident Update event.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "incident_update_id",
"in": "path",
"description": "`id` of the requested incident update",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 25
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"title": {
"type": "string",
"description": "Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.\n"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamps of a Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed Incident Update. Unconfirmed can only be a first Incident Update of an Incident. Unconfirmed Incident Updates are still visible on Hub Page.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Incident Update.
Silent event does not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
}
}
}
]
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_update_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateIncidentIncidentUpdate",
"tags": [
"Incident Update"
],
"summary": "Update an Incident Update",
"description": "Modifies existing Incident Update. Only modified attributes may be passed in payload. All other attributes will remain unchanged.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "incident_update_id",
"in": "path",
"description": "`id` of the requested incident update",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Title of this update.
Can contain only plain text.
Setting `title` to value different from current title of Incident may result in changing of Incident title.
Incident title equals to title of latest (by `start_time`) published (not draft) Incident Update `title`.\n"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.
This parameter is forbidden if `incident_type` is `resolved` because resolving an incident automatically sets all affected services to `up` status for this incident.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
}
}
},
"examples": {
"Update message": {
"description": "Change incident update message.\n",
"value": {
"body": "New incident update message."
}
},
"Publish draft": {
"description": "Publish incident update which was created as draft.\n",
"value": {
"state": "published"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 25
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"title": {
"type": "string",
"description": "Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.\n"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamps of a Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed Incident Update. Unconfirmed can only be a first Incident Update of an Incident. Unconfirmed Incident Updates are still visible on Hub Page.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Incident Update.
Silent event does not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
}
}
}
]
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_update_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Start time in future": {
"description": "Returned when `start_time` is set in future. Incidents unlike Maintenance events, can't be created in future.\n",
"value": {
"start_time": [
"cannot_be_in_future"
]
}
},
"Wrong service IDs": {
"description": "Returned when `service_id` doesn't match any service in currently used Hub. Same error is returned when there is no service with such ID as well as when service with such ID exists but in different Hub.\n",
"value": {
"service_statuses": [
"wrong_hub"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteIncidentIncidentUpdate",
"tags": [
"Incident Update"
],
"summary": "Delete an Incident Update",
"description": "Deletes Incident Update record. Records are soft-deleted which means that such deleted record can still be viewed or potentially restored.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "incident_update_id",
"in": "path",
"description": "`id` of the requested incident update",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_update_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/incident_templates": {
"post": {
"operationId": "createIncidentUpdateTemplate",
"tags": [
"Incident Update Template"
],
"summary": "Create an Incident Update Template",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "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\"]`.\n"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"silent_update": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 38
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing required values": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"template": [
"must_have_title_or_body"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listIncidentUpdateTemplates",
"tags": [
"Incident Update Template"
],
"summary": "List Incident Update Templates",
"description": "Filters and returns Incident Template records for current Hub with basic info.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "created_by_me",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
},
"description": "Behavior:\n* `true` - filter events to only those which were created by\ncurrent user,\n* `false` - filter events to only those which were **not**\ncreated by current user,\n* `all` - don't filter events by creator.\n"
},
{
"name": "deleted",
"in": "query",
"description": "Filters templates by deletion status:\n* `true` - return only templates that were deleted,\n* `false` - return only templates that were not deleted,\n* `all` - return templates without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "incident_types",
"in": "query",
"description": "Filters Incident templates by incident type value.
\nComma-separated incident types.
\nAllowed incident types:\n * investigating,\n * identified,\n * monitoring,\n * resolved.\n",
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "String that filters templates to those containing the search string in:\n- `title`,\n- `body`,\n- one of the `labels`.\n",
"schema": {
"type": "string"
}
},
{
"name": "q_label",
"in": "query",
"description": "String that filters templates to those containing the search string in one of the labels.\n",
"schema": {
"type": "string"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at"
],
"default": "created_at"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 29
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid deleted param": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/incident_templates/{incident_template_id}": {
"get": {
"operationId": "getIncidentUpdateTemplate",
"tags": [
"Incident Update Template"
],
"summary": "Retrieve an Incident Update Template",
"description": "Returns data about single template.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_template_id",
"in": "path",
"description": "`id` of the requested Incident Update Template",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 38
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_template_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateIncidentUpdateTemplate",
"tags": [
"Incident Update Template"
],
"summary": "Update an Incident Update Template",
"description": "Modifies an existing template. Only modified attributes may be passed in payload. All other attributes will remain unchanged.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_template_id",
"in": "path",
"description": "`id` of the requested Incident Update Template",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "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\"]`.\n"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"silent_update": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 38
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_template_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when some of service IDs are invalid or does not belong to current Hub.\n",
"value": {
"service_statuses": [
"not all services belong to the hub"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteIncidentUpdateTemplate",
"tags": [
"Incident Update Template"
],
"summary": "Delete an Incident Update Template",
"description": "Deletes Incident Template record. Records are soft-deleted which means that such deleted record can still be viewed.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "incident_template_id",
"in": "path",
"description": "`id` of the requested Incident Update Template",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_template_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/maintenances": {
"post": {
"operationId": "createMaintenance",
"tags": [
"Maintenance"
],
"summary": "Create a Maintenance event",
"description": "Creates a new Maintenance.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"start_time",
"end_time",
"service_statuses"
],
"properties": {
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Maintenance event:\n\n* `draft` - Not published on Hub Page.\n Draft will result in draft notifications being sent\n to Team Members,\n* `published` - Published on Hub Page.\n",
"default": "published",
"nullable": true,
"enum": [
"draft",
"published"
]
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.
Those additional notifications can be used for sending automated reminder notification to subscriptions about upcoming or just finished maintenance.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\nNot all combinations are possible for\n`offset_type` and `offset_in_min`:\n\nAllowed for `start`:\n* -129600 - 90 days,\n* -86400 - 60 days,\n* -43200 - 30 days,\n* -10080 - 7 days,\n* -2880 - 2 days,\n* -1440 - 1 days,\n* -120 - 2 hours,\n* -60 - 1 hour,\n* -30 - 30 minutes,\n* -15 - 15 minutes,\n* -5 - 5 minutes,\n* 0 - at event start (`start_time`).\n\nAllowed for `end`:\n* 0 - at event end (`end_time`).\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
}
}
},
"examples": {
"Basic example": {
"description": "Basic example of creating maintenance affecting two services.\n",
"value": {
"title": "Example maintenance title",
"start_time": "2025-05-02 12:34:56",
"end_time": "2025-05-02 13:34:56",
"body": "Maintenance body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
]
}
},
"Creating a recurring maintenance repeating every month": {
"description": "Example of creating recurring maintenance that should repeat every month.\n",
"value": {
"title": "Example maintenance title",
"start_time": "2025-05-02 12:34:56",
"end_time": "2025-05-02 13:34:56",
"body": "Maintenance body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
],
"event_repeat": {
"interval": "month"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "string"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services have been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
},
"published": {
"type": "boolean",
"description": "Was this Maintenance event published on a Hub Page.\n"
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Maintenance.
Silent events do not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
},
"recurring_placeholder": {
"type": "boolean",
"description": "Recurring maintenance schedule utilize so called Placeholder Events that are visible on Hub Page and contains all of the info as normal Maintenance events would.
However those placeholders are not fully fledged Maintenance events and some operations may not be available for those placeholder events. For example, such events when deleted are permanently removed and are not a subject to undelete.
Placeholder events are converted to normal (full) Maintenance events when either maintenance will start soon or notifications needs to be send for this event. After converting Placeholder Maintenance to normal Maintenance, such event behaves like any other normal Maintenance event.\n"
}
}
}
]
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing required values": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"title": [
"is missing"
],
"start_time": [
"is missing"
],
"end_time": [
"is missing"
]
}
},
"Wrong service IDs": {
"description": "Returned when `service_id` doesn't match any service in currently used Hub. Same error is returned when there is no service with such ID as well as when service with such ID exists but in different Hub.\n",
"value": {
"service_statuses": [
"wrong_hub"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listMaintenances",
"tags": [
"Maintenance"
],
"summary": "List Maintenance events",
"description": "Filters and returns Maintenance records for current Hub with basic info.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "created_by_me",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
},
"description": "Behavior:\n* `true` - filter events to only those which were created by\ncurrent user,\n* `false` - filter events to only those which were **not**\ncreated by current user,\n* `all` - don't filter events by creator.\n"
},
{
"name": "archived",
"in": "query",
"description": "Filters maintenance events by archived status:\n* `true` - return only maintenance events that were archived,\n* `false` - return only maintenance events that were not archived,\n* `all` - return maintenance events without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted",
"in": "query",
"description": "Filters maintenance events by deletion status:\n* `true` - return only maintenance events that were deleted,\n* `false` - return only maintenance events that were not deleted,\n* `all` - return maintenance events without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "draft",
"in": "query",
"description": "Filters events by draft status:\n* `true` - return only events that were not published yet,\n* `false` - return only events that were published,\n* `all` - return events without filtering by draft status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "period_name",
"in": "query",
"description": "Comma-separated period names.
\nFilters maintenance by period name.\n\nExamples:\n* `period_name=current`\n* `period_name=past,current`\n\nPossible period name values:\n* `past`,\n* `current`,\n* `future`.\n\nWhen not set, do not filter by period.\n",
"schema": {
"type": "string"
}
},
{
"name": "service_ids",
"in": "query",
"description": "Comma-separated string of service ids.\n\nFilters events by at least one affected service, specified in params.\n\nExample: `service_ids=1,2,3`\n",
"schema": {
"type": "string"
}
},
{
"name": "service_statuses",
"in": "query",
"description": "Comma-separated string of service statuses names.\n\nFilters events by at least one affected service with specified status.\n\nExamples:\n* `service_statuses=degraded-performance`\n* `service_statuses=up,down`\n\nPossible incident type values:\n* `up`\n* `degraded-performance`\n* `down`\n",
"schema": {
"type": "string"
}
},
{
"name": "start_time",
"in": "query",
"description": "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.\n",
"schema": {
"type": "string",
"default": "1900-01-01T00:00:00Z",
"format": "date-time"
}
},
{
"name": "end_time",
"in": "query",
"description": "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.\n",
"schema": {
"type": "string",
"default": "2199-01-01T00:00:00Z",
"format": "date-time"
}
},
{
"name": "q",
"in": "query",
"description": "String that filters events to those containing the search string in:\n- `title`,\n- `body`.\n",
"schema": {
"type": "string"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"created_at",
"start_time",
"updated_at",
"end_time"
],
"default": "start_time"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services have been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
},
"published": {
"type": "boolean",
"description": "Was this Maintenance event published on a Hub Page.\n"
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Maintenance.
Silent events do not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
},
"recurring_placeholder": {
"type": "boolean",
"description": "Recurring maintenance schedule utilize so called Placeholder Events that are visible on Hub Page and contains all of the info as normal Maintenance events would.
However those placeholders are not fully fledged Maintenance events and some operations may not be available for those placeholder events. For example, such events when deleted are permanently removed and are not a subject to undelete.
Placeholder events are converted to normal (full) Maintenance events when either maintenance will start soon or notifications needs to be send for this event. After converting Placeholder Maintenance to normal Maintenance, such event behaves like any other normal Maintenance event.\n"
}
}
}
]
}
}
},
"maxItems": 100
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid deleted param": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/maintenances/{maintenance_id}": {
"get": {
"operationId": "getMaintenance",
"tags": [
"Maintenance"
],
"summary": "Retrieve a Maintenance event",
"description": "Returns data about single maintenance event.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "maintenance_id",
"in": "path",
"description": "`id` of the requested maintenance",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "string"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services have been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
},
"published": {
"type": "boolean",
"description": "Was this Maintenance event published on a Hub Page.\n"
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Maintenance.
Silent events do not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
},
"recurring_placeholder": {
"type": "boolean",
"description": "Recurring maintenance schedule utilize so called Placeholder Events that are visible on Hub Page and contains all of the info as normal Maintenance events would.
However those placeholders are not fully fledged Maintenance events and some operations may not be available for those placeholder events. For example, such events when deleted are permanently removed and are not a subject to undelete.
Placeholder events are converted to normal (full) Maintenance events when either maintenance will start soon or notifications needs to be send for this event. After converting Placeholder Maintenance to normal Maintenance, such event behaves like any other normal Maintenance event.\n"
}
}
}
]
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid maintenance_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateMaintenance",
"tags": [
"Maintenance"
],
"summary": "Update a Maintenance event",
"description": "Modifies an existing Maintenance. Only modified attributes may be passed in payload. All other attributes will remain unchanged.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "maintenance_id",
"in": "path",
"description": "`id` of the requested maintenance",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Maintenance event:\n\n* `draft` - Not published on Hub Page.\n Draft will result in draft notifications being sent\n to Team Members,\n* `published` - Published on Hub Page.\n",
"default": "published",
"nullable": true,
"enum": [
"draft",
"published"
]
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"recurring": {
"type": "object",
"description": "Used only for Maintenance events being a part of Recurring Maintenance Schedule. Instructs API how to handle edit of an event that is repeating.\n",
"additionalProperties": false,
"properties": {
"update_following": {
"type": "boolean",
"description": "When `true` modifies currently updated event as well as all following events being a part of the same Recurring Maintenance Schedule.
When `false` modifies only currently updated event. Following events in same Recurring Maintenance Schedule remains unchanged.\n"
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"recurring": {
"type": "object",
"required": [
"update_following"
],
"additionalProperties": false,
"properties": {
"update_following": {
"type": "boolean"
}
}
}
}
}
]
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "string"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services have been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
},
"published": {
"type": "boolean",
"description": "Was this Maintenance event published on a Hub Page.\n"
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Maintenance.
Silent events do not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
},
"recurring_placeholder": {
"type": "boolean",
"description": "Recurring maintenance schedule utilize so called Placeholder Events that are visible on Hub Page and contains all of the info as normal Maintenance events would.
However those placeholders are not fully fledged Maintenance events and some operations may not be available for those placeholder events. For example, such events when deleted are permanently removed and are not a subject to undelete.
Placeholder events are converted to normal (full) Maintenance events when either maintenance will start soon or notifications needs to be send for this event. After converting Placeholder Maintenance to normal Maintenance, such event behaves like any other normal Maintenance event.\n"
}
}
}
]
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid maintenance_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong service IDs": {
"description": "Returned when `service_id` doesn't match any service in currently used Hub. Same error is returned when there is no service with such ID as well as when service with such ID exists but in different Hub.\n",
"value": {
"service_statuses": [
"wrong_hub"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteMaintenance",
"tags": [
"Maintenance"
],
"summary": "Delete a Maintenance event",
"description": "Deletes Maintenance record. Records are soft-deleted which means that such deleted record can still be viewed or potentially restored.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "maintenance_id",
"in": "path",
"description": "`id` of the requested maintenance",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/maintenance_templates": {
"post": {
"operationId": "createMaintenanceTemplate",
"tags": [
"Maintenance Template"
],
"summary": "Create a Maintenance Template",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.
Maximum allowed value is 99h:59min (5999 minutes).\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "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\"]`.\n"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 60
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing required values": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"template": [
"must_have_title_or_body"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listMaintenanceTemplates",
"tags": [
"Maintenance Template"
],
"summary": "List Maintenance Templates",
"description": "Filters and returns Maintenance Template records for current Hub with basic info.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "created_by_me",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
},
"description": "Behavior:\n* `true` - filter events to only those which were created by\ncurrent user,\n* `false` - filter events to only those which were **not**\ncreated by current user,\n* `all` - don't filter events by creator.\n"
},
{
"name": "deleted",
"in": "query",
"description": "Filters templates by deletion status:\n* `true` - return only templates that were deleted,\n* `false` - return only templates that were not deleted,\n* `all` - return templates without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "q",
"in": "query",
"description": "Query string",
"schema": {
"type": "string"
}
},
{
"name": "q_label",
"in": "query",
"description": "Query label",
"schema": {
"type": "string"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at"
],
"default": "created_at"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 51
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.\n"
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid deleted param": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/maintenance_templates/{maintenance_template_id}": {
"get": {
"operationId": "getMaintenanceTemplate",
"tags": [
"Maintenance Template"
],
"summary": "Retrieve a Maintenance Template",
"description": "Returns data about single template.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "maintenance_template_id",
"in": "path",
"description": "`id` of the requested Maintenance Template",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 60
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid maintenance_template_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateMaintenanceTemplate",
"tags": [
"Maintenance Template"
],
"summary": "Update a Maintenance Template",
"description": "Modifies an existing template. Only modified attributes may be passed in payload. All other attributes will remain unchanged.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "maintenance_template_id",
"in": "path",
"description": "`id` of the requested Maintenance Template",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.
Maximum allowed value is 99h:59min (5999 minutes).\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "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\"]`.\n"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 60
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid maintenance_template_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when some of service IDs are invalid or does not belong to current Hub.\n",
"value": {
"service_statuses": [
"not all services belong to the hub"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteMaintenanceTemplate",
"tags": [
"Maintenance Template"
],
"summary": "Delete a Maintenance Template",
"description": "Deletes Maintenance Template record. Records are soft-deleted which means that such deleted record can still be viewed.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "maintenance_template_id",
"in": "path",
"description": "`id` of the requested Maintenance Template",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid maintenance_template_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscribers": {
"post": {
"operationId": "createSubscriber",
"tags": [
"Subscriber"
],
"summary": "Create a Subscriber",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"subscriptions"
],
"properties": {
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"address",
"method_name",
"services_selection"
],
"properties": {
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
},
"subscriber_id": {
"type": "integer",
"description": "`id` of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.\n",
"example": 9
}
}
},
"minItems": 1
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 67
},
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscriber has been deleted.",
"example": false
}
}
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Already subscribed": {
"description": "Returned when address is already subscribed to current Hub.
`subscriptions[0]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions[0].address": [
"already subscribed",
"already taken"
]
}
},
"Duplicated method": {
"description": "Returned when there is more than one subscription for any method name.
`subscriptions[0]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions": [
"can not have multiple identical methods"
]
}
},
"Invalid address": {
"description": "Returned when address of subscription is invalid for given method name.
`subscriptions[2]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions[2].address": [
"invalid"
]
}
},
"Invalid service IDs": {
"description": "Returned when address of subscription is invalid for given method name.
`subscriptions[1]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions[1].services_selection": [
"invalid"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listSubscribers",
"tags": [
"Subscriber"
],
"summary": "List Subscribers",
"description": "Filters and returns Subscribers for current Hub with basic info.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "deleted",
"in": "query",
"description": "Filters subscribers by deletion status:\n* `true` - return only subscribers that were deleted,\n* `false` - return only subscribers that were not deleted,\n* `all` - return subscribers without filtering by deleted status.\n\nPlease note that this filter work on subscriber level and does not\ncheck subscriptions deletion status during filtering.
\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "q",
"in": "query",
"description": "String that filters subscribers to those containing the search string in:\n- `idp_id`.\n",
"schema": {
"type": "string",
"example": "internal-identifier-at-company.com"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at",
"updated_at"
],
"default": "created_at"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 64
},
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscriber has been deleted.",
"example": false
}
}
}
}
},
"maxItems": 100
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong parameter value": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscribers/{subscriber_id}": {
"get": {
"operationId": "getSubscriber",
"tags": [
"Subscriber"
],
"summary": "Retrieve a Subscriber",
"description": "Returns data about single Subscriber.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 67
},
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscriber has been deleted.",
"example": false
}
}
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateSubscriber",
"tags": [
"Subscriber"
],
"summary": "Updates a Subscriber",
"description": "Modifies existing Subscriber.
Only modified attributes may be passed in payload. All other attributes will remain unchanged.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 67
},
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscriber has been deleted.",
"example": false
}
}
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid subscriber_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Duplicated IDP ID": {
"description": "Returned when `idp_id` has already been used in current Hub.\n",
"value": {
"idp_id": [
"already taken"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteSubscriber",
"tags": [
"Subscriber"
],
"summary": "Delete a Subscriber",
"description": "Deletes Subscriber record.
Records are soft-deleted which means that such deleted record can still be viewed.
Deleting Subscriber also deletes all its Subscriptions.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"Success": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions": {
"post": {
"operationId": "createSubscriberSubscription",
"tags": [
"Subscriber Subscription"
],
"summary": "Create a Subscription",
"description": "Creates a new Subscription for existing Subscriber.
\nBesides regular validation - like address correctness - there are\na few additional constraints:\n- Address has to be unique for current Hub,\n- Single Subscriber can't have multiple subscriptions with same method name.\n For example it's not allowed for one Subscriber to have for example\n two email subscriptions.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"address",
"method_name",
"services_selection"
],
"properties": {
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
},
"subscriber_id": {
"type": "integer",
"description": "`id` of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.\n",
"example": 9
}
}
},
"examples": {
"Minimal example": {
"description": "Minimal example creating email subscription.\n",
"value": {
"address": "example@statushub.com",
"method_name": "email",
"services_selection": {
"all": true
}
}
},
"Basic example with less verbose and services selection": {
"description": "Example creating email subscription with less verbose option and services selection.\n",
"value": {
"address": "example@statushub.com",
"method_name": "email",
"services_selection": {
"service_ids": [
17155,
17363
]
},
"less_verbose": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Duplicated address": {
"description": "Returned when there is more than one subscription for any method name for current Hub.\n",
"value": {
"address": [
"already taken",
"already subscribed"
]
}
},
"Duplicated method": {
"description": "Returned when there is more than one subscription for any method name for current Subscriber.\n",
"value": {
"method_name": [
"already subscribed"
]
}
},
"Invalid address": {
"description": "Returned when address of subscription is invalid for given method name.\n",
"value": {
"address": [
"invalid"
]
}
},
"Invalid Subscriber ID": {
"description": "Returned when SubscriberID is invalid.
Returned also when trying to create Subscription for deleted Subscriber.\n",
"value": {
"subscriber_id": [
"invalid"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listSubscriberSubscriptions",
"tags": [
"Subscriber Subscription"
],
"summary": "List Subscriptions",
"description": "Filters and returns Subscriptions with basic info for existing Subscriber.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "deleted",
"in": "query",
"description": "Filters subscriptions by deletion status:\n* `true` - return only subscriptions that were deleted,\n* `false` - return only subscriptions that were not deleted,\n* `all` - return subscriptions without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted_after",
"in": "query",
"description": "Filters Subscriptions by the timestamp of record deletion.
\nLooks for Subscriptions deleted on or after the `deleted_after`\ntimestamp.
\nISO8601 formatted time (UTC).\n",
"schema": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T08:29:00Z"
}
},
{
"name": "q",
"in": "query",
"description": "String that filters subscriptions to those containing\nthe search string in:\n- `address`,\n- `label`.\n",
"schema": {
"type": "string"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at",
"updated_at"
],
"default": "created_at"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 78
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 79
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
}
}
},
"maxItems": 100
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when SubscriberID is invalid.
\n",
"value": {
"message": "subscriber not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong parameter value": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions/{subscription_id}": {
"get": {
"operationId": "getSubscriberSubscription",
"tags": [
"Subscriber Subscription"
],
"summary": "Retrieve a Subscription",
"description": "Returns data about single Subscription.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when SubscriberID is invalid.
\n",
"value": {
"message": "subscriber not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong parameter value": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateSubscriberSubscription",
"tags": [
"Subscriber Subscription"
],
"summary": "Update a Subscription",
"description": "Modifies existing Subscription.
Only modified attributes may be passed in payload. All other attributes will remain unchanged.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"services_selection"
],
"properties": {
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when SubscriberID is invalid.
\n",
"value": {
"message": "subscriber not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing services selection": {
"description": "Returned when `services_selection` parameter is missing or incomplete.
Example of incomplete `services_selection` is `{\"services_selection\": {\"all\": false}}` which would indicate that a subset of services should be used but the services list was not provided.\n",
"value": {
"services_selection": [
"is missing"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteSubscriberSubscription",
"tags": [
"Subscriber Subscription"
],
"summary": "Delete a Subscription",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"Success": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when SubscriberID is invalid.
\n",
"value": {
"message": "subscriber not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscribers/{subscriber_id}/subscriptions/{subscription_id}/restore": {
"put": {
"operationId": "restoreSubscriberSubscription",
"tags": [
"Subscriber Subscription"
],
"summary": "Restore a Subscription",
"description": "Restores deleted Subscription.
\nMay fail if restoring would result in record\nthat is not valid, for example because subscription with that address\nalready exists.
\nRestoring depending on data may either:\n- Recreate the record as a new one with new ID,\n- Undelete the record preserving it ID.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
},
"Not allowed": {
"description": "Returned when restoring subscription is not allowed because such subscription would violate validations.
For example when attempting to restore subscription with address that is already being used by an active (not deleted) subscription in the same Hub.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when SubscriberID is invalid.
\n",
"value": {
"message": "subscriber not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscriptions": {
"post": {
"operationId": "createSubscription",
"tags": [
"Subscription"
],
"summary": "Create a Subscription",
"description": "Creates a new Subscription. Creates Subscriber record as well.
\nBesides regular validation - like address correctness - there are\na few additional constraints:\n- Address has to be unique for current Hub,\n- Single Subscriber can't have multiple subscriptions with same method name.\n For example it's not allowed for one Subscriber to have for example\n two email subscriptions.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"address",
"method_name",
"services_selection"
],
"properties": {
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
},
"subscriber_id": {
"type": "integer",
"description": "`id` of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.\n",
"example": 9
}
}
},
"examples": {
"Minimal example": {
"description": "Minimal example creating email subscription.\n",
"value": {
"address": "example@statushub.com",
"method_name": "email",
"services_selection": {
"all": true
}
}
},
"Basic example with less verbose and services selection": {
"description": "Example creating email subscription with less verbose option and services selection.\n",
"value": {
"address": "example@statushub.com",
"method_name": "email",
"services_selection": {
"service_ids": [
17155,
17363
]
},
"less_verbose": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Duplicated address": {
"description": "Returned when there is more than one subscription for any method name for current Hub.\n",
"value": {
"address": [
"already taken",
"already subscribed"
]
}
},
"Duplicated method": {
"description": "Returned when there is more than one subscription for any method name for current Subscriber.\n",
"value": {
"method_name": [
"already subscribed"
]
}
},
"Invalid address": {
"description": "Returned when address of subscription is invalid for given method name.\n",
"value": {
"address": [
"invalid"
]
}
}
}
}
}
}
}
},
"get": {
"operationId": "listSubscriptions",
"tags": [
"Subscription"
],
"summary": "List Subscriptions",
"description": "Filters and returns Subscriptions with basic info for current Hub.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "deleted",
"in": "query",
"description": "Filters subscriptions by deletion status:\n* `true` - return only subscriptions that were deleted,\n* `false` - return only subscriptions that were not deleted,\n* `all` - return subscriptions without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted_after",
"in": "query",
"description": "Filters Subscriptions by the timestamp of record deletion.
\nLooks for Subscriptions deleted on or after the `deleted_after`\ntimestamp.
\nISO8601 formatted time (UTC).\n",
"schema": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T08:29:00Z"
}
},
{
"name": "q",
"in": "query",
"description": "String that filters subscriptions to those containing\nthe search string in:\n- `address`,\n- `label`.\n",
"schema": {
"type": "string"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at",
"updated_at"
],
"default": "created_at"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 78
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 79
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
}
}
},
"maxItems": 100
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong parameter value": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscriptions/{subscription_id}": {
"get": {
"operationId": "getSubscription",
"tags": [
"Subscription"
],
"summary": "Retrieve a Subscription",
"description": "Returns data about single Subscription.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong parameter value": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid extend param": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateSubscription",
"tags": [
"Subscription"
],
"summary": "Update a Subscription",
"description": "Modifies existing Subscription.
Only modified attributes may be passed in payload. All other attributes will remain unchanged.",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"services_selection"
],
"properties": {
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Missing services selection": {
"description": "Returned when `services_selection` parameter is missing or incomplete.
Example of incomplete `services_selection` is `{\"services_selection\": {\"all\": false}}` which would indicate that a subset of services should be used but the services list was not provided.\n",
"value": {
"services_selection": [
"is missing"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteSubscription",
"tags": [
"Subscription"
],
"summary": "Delete a Subscription",
"description": "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.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
},
"examples": {
"Success": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscriber ID": {
"description": "Returned when SubscriberID is invalid.
\n",
"value": {
"message": "subscriber not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/subscriptions/{subscription_id}/restore": {
"put": {
"operationId": "restoreSubscription",
"tags": [
"Subscription"
],
"summary": "Restore a Subscription",
"description": "Restores deleted Subscription.
\nMay fail if restoring would result in record\nthat is not valid for example because subscription with that address already\nexists.
\nRestoring depending on data may either:\n- Recreate the record as a new one with new ID,\n- Undelete the record preserving it ID.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
},
"Not allowed": {
"description": "Returned when restoring subscription is not allowed because such subscription would violate validations.
For example when attempting to restore subscription with address that is already being used by an active (not deleted) subscription in the same Hub.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid Subscription ID": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/groups": {
"get": {
"operationId": "listGroups",
"tags": [
"Group"
],
"summary": "List Groups",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "archived",
"in": "query",
"description": "Filters groups by archived status:\n* `true` - return only groups that were archived,\n* `false` - return only groups that were not archived,\n* `all` - return groups without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted",
"in": "query",
"description": "Filters groups by deletion status:\n* `true` - return only groups that were deleted,\n* `false` - return only groups that were not deleted,\n* `all` - return groups without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "q",
"in": "query",
"description": "String that filters groups to those containing the search string in:\n- `name`.\n",
"schema": {
"type": "string"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 100
},
"name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong parameter value": {
"description": "Returned when archived param is invalid.\n",
"value": {
"archived": [
"must be one of: true, false, all"
]
}
},
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
},
"post": {
"operationId": "createGroup",
"tags": [
"Group"
],
"summary": "Create a Group",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 101
},
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Empty name": {
"description": "Returned when trying to create a group without a name.\n",
"value": {
"name": [
"must be filled"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/groups/{group_id}": {
"get": {
"operationId": "getGroup",
"tags": [
"Group"
],
"summary": "Retrieve a Group",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"in": "path",
"description": "`id` of the group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 101
},
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid group_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateGroup",
"tags": [
"Group"
],
"summary": "Update a Group",
"description": "Updates existing group.
Request valid only in scope of Primary or Standalone Hub and can't be used in scope of a Connected Hub.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"in": "path",
"description": "`id` of the group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 101
},
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Malformed JSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Group is archived": {
"description": "Returned when trying to modify group that was archived.\n",
"value": {
"message": "not authorized"
}
},
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Empty name": {
"description": "Returned when trying to set an empty group name.\n",
"value": {
"name": [
"must be filled"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteGroup",
"tags": [
"Group"
],
"summary": "Delete a Group",
"description": "Deletes existing group and all its services.
\nRequest valid only in the scope of Primary or Standalone Hub and can't\nbe used in the scope of a Connected Hub.
\n\nDeleting a group also deletes:\n- All services in that group,\n- Events if there are events that after deleting this group with\n its services would be left without any other services.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"in": "path",
"description": "`id` of the group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
},
"Group is archived": {
"description": "Returned when trying to modify group that was archived.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/groups/{group_id}/archive": {
"put": {
"operationId": "archiveGroup",
"tags": [
"Group"
],
"summary": "Archive a Group",
"description": "Archives existing group and all its services.
\nRequest valid only in scope of Primary or Standalone Hub and can't\nbe used in scope of a Connected Hub.
\n\nDeleting a group also archives:\n- All services in that group,\n- Events if there are events that after deleting this group with\n its services would be left without any other services.\n\nThe difference between deleting and archiving can be summarized by:\n- Both archived and deleted records are not visible on Hub Page,\n- Unlike deleted records, archived records are still visible in Control\n Panel but as a read-only records.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"in": "path",
"description": "`id` of the group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Group is archived": {
"description": "Returned when trying to modify group that was archived.\n",
"value": {
"message": "not authorized"
}
},
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/hubs/{subdomain}/groups/{group_id}/reorder": {
"put": {
"operationId": "reorderGroup",
"tags": [
"Group"
],
"summary": "Update a Group position",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"in": "path",
"description": "`id` of the group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"reference_id",
"position"
],
"properties": {
"reference_id": {
"type": "integer",
"description": "The ID of another group which position will be used as a reference to new position of reordered group.\n"
},
"position": {
"type": "string",
"description": "Specifies if reordered group should be put before or after reference group specified by ID in `reference_id` parameter.\n",
"enum": [
"before",
"after"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Group is archived": {
"description": "Returned when trying to modify group that was archived.\n",
"value": {
"message": "not authorized"
}
},
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/services": {
"get": {
"operationId": "listServices",
"tags": [
"Service"
],
"summary": "List Services",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"description": "Filters services to only those which belong to group with ID specified by `group_id`.\n",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false
},
{
"name": "archived",
"in": "query",
"description": "Filters services by archived status:\n* `true` - return only services that were archived,\n* `false` - return only services that were not archived,\n* `all` - return services without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted",
"in": "query",
"description": "Filters services by deletion status:\n* `true` - return only services that were deleted,\n* `false` - return only services that were not deleted,\n* `all` - return services without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "q",
"in": "query",
"description": "String that filters services to those containing the search string in:\n- `name`,\n- `custom_id`.\n",
"schema": {
"type": "string"
}
},
{
"name": "per_group_sort",
"in": "query",
"description": "Alters behavior of `sort_prop`:\n- (default) If `per_group_sort` is `true` - Sort by the `sort_prop`\n in each connected group individually,\n- if `per_group_sort` is `false` - Sort by `sort_prop` globally so\n output will contain connected services ignoring the order\n of connected groups.
\n This means that connected services from same connected group\n may be interleaved by connected services from different\n connected groups.
\n One exception is `position` `sort_prop` which forces `per_group_sort`\n to be `true` regardless of actual value used in request.
\n\n If `per_group_sort` is `true` the order of connected groups\n is always determined by connected group `position`.
\n",
"schema": {
"default": true,
"type": "boolean"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.
\nThe final sorting depends also on `per_group_sort` parameter:\n- (default) If `per_group_sort` is `true` - Sort by the `sort_prop`\n in each group individually,\n- if `per_group_sort` is `false` - Sort by `sort_prop` globally so\n output will contain services ignoring the order of group.
\n This means that services from same group may be interleaved by services\n from different groups.
\nOne exception is `position` `sort_prop` which forces `per_group_sort`\nto be `true` regardless of actual value used in request.
\n\nIf `per_group_sort` is `true` the order of groups is always determined\nby group `position`.
\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction inside each Group.
\nIt does not affect the order of groups which is fixed to `position`.
\nServices will be sorted by `sort_prop` inside each group individually.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 102
},
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 103
},
"name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Wrong parameter value": {
"description": "Returned when archived param is invalid.\n",
"value": {
"archived": [
"must be one of: true, false, all"
]
}
},
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
},
"post": {
"operationId": "createService",
"tags": [
"Service"
],
"summary": "Create a Service",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"group_id",
"name"
],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 106
},
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 107
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
},
"token": {
"type": "string",
"description": "Unique token value that is being used to connect external integrations to StatusHub.
Typically all integration URLs are using the `token` value so knowing the `token` value allows to construct various integrations URLs programmatically.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Empty name": {
"description": "Returned when trying to create a service without a name.\n",
"value": {
"name": [
"must be filled"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/services/{service_id}": {
"get": {
"operationId": "getService",
"tags": [
"Service"
],
"summary": "Retrieve a Service",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 106
},
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 107
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
},
"token": {
"type": "string",
"description": "Unique token value that is being used to connect external integrations to StatusHub.
Typically all integration URLs are using the `token` value so knowing the `token` value allows to construct various integrations URLs programmatically.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateService",
"tags": [
"Service"
],
"summary": "Update a Service",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 106
},
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 107
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
},
"token": {
"type": "string",
"description": "Unique token value that is being used to connect external integrations to StatusHub.
Typically all integration URLs are using the `token` value so knowing the `token` value allows to construct various integrations URLs programmatically.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
},
"Empty name": {
"description": "Returned when trying to set an empty service name.\n",
"value": {
"name": [
"must be filled"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteService",
"tags": [
"Service"
],
"summary": "Delete a Service",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
},
"Service is archived": {
"description": "Returned when trying to modify service that was archived.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/services/{service_id}/archive": {
"put": {
"operationId": "archiveService",
"tags": [
"Service"
],
"summary": "Archive a Service",
"description": "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`.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/services/{service_id}/reorder": {
"put": {
"operationId": "reorderService",
"tags": [
"Service"
],
"summary": "Update a Service position",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"reference_id",
"position"
],
"properties": {
"reference_id": {
"type": "integer",
"description": "The ID of another service which position will be used as a reference to new position of reordered service.\n"
},
"position": {
"type": "string",
"description": "Specifies if reordered service should be put before or after reference service specified by ID in `reference_id` parameter.\n",
"enum": [
"before",
"after"
]
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/services/{service_id}/integrations": {
"get": {
"operationId": "listServiceIntegrations",
"tags": [
"Service Integration"
],
"summary": "List service integrations",
"description": "List all of available integrations for a service.
\nIntegration version is used to indicate the generation of integrations\nwhere `v1` are the basic integrations available in StatusHub for long time.\nwhile `v2` integrations are much more capable and all newly introduced\nintegrations will be added in `v2` version.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "enabled",
"in": "query",
"description": "Filter by enabled status",
"schema": {
"type": "boolean"
}
},
{
"name": "version",
"in": "query",
"description": "Filter by integration version.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"schema": {
"type": "string",
"enum": [
"v1",
"v2"
]
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Is integration enabled on this service\n",
"example": true
},
"slug": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
],
"example": "generic_hook_v2"
},
"version": {
"type": "string",
"description": "Version of the integration.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"enum": [
"v1",
"v2"
],
"example": "v2"
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/services/{service_id}/integrations/{integration_slug}": {
"get": {
"operationId": "showServiceIntegration",
"tags": [
"Service Integration"
],
"summary": "Retrieve a service integration details",
"description": "Show service integration details\nWith the exception of Pingdom integration, all other integrations are\nusing per-service URL for connection.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "integration_slug",
"in": "path",
"description": "Integration slug",
"schema": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
]
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Is integration enabled on this service\n",
"example": true
},
"slug": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
],
"example": "generic_hook_v2"
},
"version": {
"type": "string",
"description": "Version of the integration.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"enum": [
"v1",
"v2"
],
"example": "v2"
},
"url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Except for Pingdom integration, `url` is unique per-Service URL that\nshould be used to connect 3rd party service to StatusHub Service.
\nBehavior of this field varies between `v1` and `v2` integrations:\n- For `v1` integrations, this URL share same token part between\n integrations and `url` is never blank,\n- For `v2` integrations, each integration may use different token.
\n `url` is blank if `v2` integration is not enabled.\n",
"example": "https://app.statushub.io/hooks/generic_hook_v2?token=a18331da-19a5-46f1-8bfa-06a6a31f1d10"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateServiceIntegration",
"tags": [
"Service Integration"
],
"summary": "Update service integrations",
"description": "Update service integrations",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "integration_slug",
"in": "path",
"description": "Integration slug",
"schema": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
]
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Should integration be enabled on this service\n",
"example": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Is integration enabled on this service\n",
"example": true
},
"slug": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
],
"example": "generic_hook_v2"
},
"version": {
"type": "string",
"description": "Version of the integration.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"enum": [
"v1",
"v2"
],
"example": "v2"
},
"url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Except for Pingdom integration, `url` is unique per-Service URL that\nshould be used to connect 3rd party service to StatusHub Service.
\nBehavior of this field varies between `v1` and `v2` integrations:\n- For `v1` integrations, this URL share same token part between\n integrations and `url` is never blank,\n- For `v2` integrations, each integration may use different token.
\n `url` is blank if `v2` integration is not enabled.\n",
"example": "https://app.statushub.io/hooks/generic_hook_v2?token=a18331da-19a5-46f1-8bfa-06a6a31f1d10"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/connected_groups": {
"get": {
"operationId": "listConnectedGroups",
"tags": [
"Connected Group"
],
"summary": "List Connected Groups",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "archived",
"in": "query",
"description": "Filters groups by archived status:\n* `true` - return only groups that were archived,\n* `false` - return only groups that were not archived,\n* `all` - return groups without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted",
"in": "query",
"description": "Filters groups by deletion status:\n* `true` - return only groups that were deleted,\n* `false` - return only groups that were not deleted,\n* `all` - return groups without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "q",
"in": "query",
"description": "String that filters groups to those containing the search string in:\n- `name`.\n",
"schema": {
"type": "string"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 100
},
"name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid deleted param": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid Hub Type": {
"description": "Returned when performing on Primary or Standalone Hub a request valid only for Connected Hub.\n",
"value": {
"message": [
"hub must be connected"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/connected_groups/{group_id}": {
"get": {
"operationId": "getConnectedGroup",
"tags": [
"Connected Group"
],
"summary": "Retrieve a Connected Group",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"in": "path",
"description": "ID of Group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 101
},
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid incident_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Primary or Standalone Hub a request valid only for Connected Hub.\n",
"value": {
"message": [
"hub must be connected"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/connected_services": {
"get": {
"operationId": "listConnectedServices",
"tags": [
"Connected Service"
],
"summary": "List Connected Services",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"description": "Filters services to only those which belong to group with ID specified by `group_id`.\n",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false
},
{
"name": "archived",
"in": "query",
"description": "Filters services by archived status:\n* `true` - return only services that were archived,\n* `false` - return only services that were not archived,\n* `all` - return services without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "deleted",
"in": "query",
"description": "Filters services by deletion status:\n* `true` - return only services that were deleted,\n* `false` - return only services that were not deleted,\n* `all` - return services without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
{
"name": "q",
"in": "query",
"description": "String that filters services to those containing the search string in:\n- `name`,\n- `custom_id`.\n",
"schema": {
"type": "string"
}
},
{
"name": "per_group_sort",
"in": "query",
"description": "Alters behavior of `sort_prop`:\n- (default) If `per_group_sort` is `true` - Sort by the `sort_prop`\n in each connected group individually,\n- if `per_group_sort` is `false` - Sort by `sort_prop` globally so\n output will contain connected services ignoring the order\n of connected groups.
\n This means that connected services from same connected group\n may be interleaved by connected services from different\n connected groups.
\n One exception is `position` `sort_prop` which forces `per_group_sort`\n to be `true` regardless of actual value used in request.
\n\n If `per_group_sort` is `true` the order of connected groups\n is always determined by connected group `position`.
\n",
"schema": {
"default": true,
"type": "boolean"
}
},
{
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.
\nThe final sorting depends also on `per_group_sort` parameter:\n- (default) If `per_group_sort` is `true` - Sort by the `sort_prop`\n in each connected group individually,\n- if `per_group_sort` is `false` - Sort by `sort_prop` globally so\n output will contain connected services ignoring the order\n of connected groups.
\n This means that connected services from same connected group\n may be interleaved by connected services from different\n connected groups.
\n One exception is `position` `sort_prop` which forces `per_group_sort`\n to be `true` regardless of actual value used in request.
\n\nIf `per_group_sort` is `true` the order of connected groups\nis always determined by connected group `position`.
\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
{
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction inside each Group.
\nIt does not affect the order of groups which is fixed to `position`.
\nServices will be sorted by `sort_prop` inside each group individually.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
{
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
{
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"type": "object",
"required": [],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
{
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 102
},
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 103
},
"name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
}
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid deleted param": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"Invalid Hub Type": {
"description": "Returned when performing on Primary or Standalone Hub a request valid only for Connected Hub.\n",
"value": {
"message": [
"hub must be connected"
]
}
}
}
}
}
}
}
},
"post": {
"operationId": "createConnectedService",
"tags": [
"Connected Service"
],
"summary": "Create a Connected Service",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [
"service_id"
],
"properties": {
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 106
},
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 107
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
},
"token": {
"type": "string",
"description": "Unique token value that is being used to connect external integrations to StatusHub.
Typically all integration URLs are using the `token` value so knowing the `token` value allows to construct various integrations URLs programmatically.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Primary or Standalone Hub a request valid only for Connected Hub.\n",
"value": {
"message": [
"hub must be connected"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/connected_services/{service_id}": {
"get": {
"operationId": "getConnectedService",
"tags": [
"Connected Service"
],
"summary": "Retrieve a Connected Service",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "ID of Service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 106
},
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 107
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
},
"token": {
"type": "string",
"description": "Unique token value that is being used to connect external integrations to StatusHub.
Typically all integration URLs are using the `token` value so knowing the `token` value allows to construct various integrations URLs programmatically.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Primary or Standalone Hub a request valid only for Connected Hub.\n",
"value": {
"message": [
"hub must be connected"
]
}
}
}
}
}
}
}
},
"delete": {
"operationId": "deleteConnectedService",
"tags": [
"Connected Service"
],
"summary": "Delete a Connected Service",
"description": "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.
\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "ID of Service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"message": {
"type": "string"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"Invalid service_id": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid Hub Type": {
"description": "Returned when performing on Primary or Standalone Hub a request valid only for Connected Hub.\n",
"value": {
"message": [
"hub must be connected"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/uptime": {
"get": {
"operationId": "getUptime",
"tags": [
"Uptime"
],
"summary": "Retrieve Hub uptime value",
"description": "Returns uptime for a Hub which is based on uptime of all services\nin that Hub for a given date range.
\nHub is considered up if all of its services are not `down`.\nEvery time frame when at least one of Hub services is down, is considered\nas downtime for this Hub.
\nMaximum length of date range is 18 months.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "start_date",
"in": "query",
"description": "Start date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "End date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"uptime": {
"type": "number",
"description": "Uptime value for the requested period. Value is between 0.0 and 1.0, where 0 means no uptime and 1 means 100% uptime.
Uptime value is always rounded down.\n",
"minimum": 0,
"maximum": 1,
"example": 0.9995
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid end date": {
"description": "Returned when date param can't be parsed as valid date.
For example: `end_date=2025-02-31`\n",
"value": {
"end_date": [
"must be a date"
]
}
},
"start and end date too far apart": {
"description": "Returned when `end_date` param is too far apart from `start_date`.
Response specifies maximum value of `end_date` that can be used with provided `start_date`.\n",
"value": {
"end_date": [
"must be less than or equal to 2024-08-01"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/uptime/daily": {
"get": {
"operationId": "getDailyUptime",
"tags": [
"Uptime"
],
"summary": "Returns Hub uptime data with daily granularity",
"description": "Returns uptime for a Hub with daily granularity.\nHub uptime is based on uptime of all services in that Hub for every\nday.
\nDays are aligned to UTC timezone.
\nHub is considered up for given day if all of its services are not `down`\nin that day.\nEvery time frame when at least one of Hub services is down, is considered\nas downtime for this Hub.
\nMaximum length of date range is 18 months.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "start_date",
"in": "query",
"description": "Start date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "End date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": {
"type": "number",
"description": "Uptime value for the requested period. Value is between 0.0 and 1.0, where 0 means no uptime and 1 means 100% uptime.
Uptime value is always rounded down.\n",
"minimum": 0,
"maximum": 1,
"example": 0.9995
},
"example": {
"2023-01-01": 0.9995,
"2023-01-02": 1,
"2023-01-03": 0.68351,
"2023-01-04": 0.99999,
"2023-01-05": 1
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid end date": {
"description": "Returned when date param can't be parsed as valid date.
For example: `end_date=2025-02-31`\n",
"value": {
"end_date": [
"must be a date"
]
}
},
"start and end date too far apart": {
"description": "Returned when `end_date` param is too far apart from `start_date`.
Response specifies maximum value of `end_date` that can be used with provided `start_date`.\n",
"value": {
"end_date": [
"must be less than or equal to 2024-08-01"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/uptime/groups/{group_id}": {
"get": {
"operationId": "getGroupUptime",
"tags": [
"Uptime"
],
"summary": "Retrieve group uptime value",
"description": "Returns uptime for a group which is based on uptime of all services\nin that group for a given date range.
\nGroup is considered up if all of its services are not `down`.\nEvery time frame when at least one of group services is down, is considered\nas downtime for this group.
\nMaximum length of date range is 18 months.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "group_id",
"in": "path",
"description": "`id` of the group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "start_date",
"in": "query",
"description": "Start date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "End date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"uptime": {
"type": "number",
"description": "Uptime value for the requested period. Value is between 0.0 and 1.0, where 0 means no uptime and 1 means 100% uptime.
Uptime value is always rounded down.\n",
"minimum": 0,
"maximum": 1,
"example": 0.9995
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid end date": {
"description": "Returned when date param can't be parsed as valid date.
For example: `end_date=2025-02-31`\n",
"value": {
"end_date": [
"must be a date"
]
}
},
"start and end date too far apart": {
"description": "Returned when `end_date` param is too far apart from `start_date`.
Response specifies maximum value of `end_date` that can be used with provided `start_date`.\n",
"value": {
"end_date": [
"must be less than or equal to 2024-08-01"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/uptime/services/{service_id}": {
"get": {
"operationId": "getServiceUptime",
"tags": [
"Uptime"
],
"summary": "Retrieve service uptime value",
"description": "Returns uptime for a service for a given date range.
\nService is considered up its status is not `down`.\nMaximum length of date range is 18 months.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
{
"name": "start_date",
"in": "query",
"description": "Start date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "end_date",
"in": "query",
"description": "End date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"uptime": {
"type": "number",
"description": "Uptime value for the requested period. Value is between 0.0 and 1.0, where 0 means no uptime and 1 means 100% uptime.
Uptime value is always rounded down.\n",
"minimum": 0,
"maximum": 1,
"example": 0.9995
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid end date": {
"description": "Returned when date param can't be parsed as valid date.
For example: `end_date=2025-02-31`\n",
"value": {
"end_date": [
"must be a date"
]
}
},
"start and end date too far apart": {
"description": "Returned when `end_date` param is too far apart from `start_date`.
Response specifies maximum value of `end_date` that can be used with provided `start_date`.\n",
"value": {
"end_date": [
"must be less than or equal to 2024-08-01"
]
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/external_applications": {
"get": {
"operationId": "listExternalApplications",
"tags": [
"External Application"
],
"summary": "List External Application installations",
"description": "List all of currently supported external applications as well as the\nstatus of the integration for current Hub.
\nIf app is not enabled, it will not work even if its installed with correct\ntoken.
\nCurrently supported applications are:\n- Minimal Widget - Small and basic version of StatusHub widget\n intended to be used in places requiring small visual size of the widget,\n- Widget - Default Statushub widget,\n- Zendesk - StatusHub App for Zendesk -\n [Zendesk Marketplace link](https://www.zendesk.com/marketplace/apps/support/127482/statushub/)\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
}
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
}
},
"/hubs/{subdomain}/external_applications/{external_application_slug}": {
"get": {
"operationId": "getExternalApplication",
"tags": [
"External Application"
],
"summary": "Retrieve an external application installation details",
"description": "Show details of a specific External Application installation.
\nFor security reasons, token is not returned. If app token is lost,\nin Management API v3 the only way to retrieve a token is to generate\na new one with reset token operation.
\nIn order to install the application, please refer to documentation of\nrespective CP2 which will contain all necessary snippets and links.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "external_application_slug",
"in": "path",
"description": "External Application slug",
"schema": {
"type": "string",
"enum": [
"minimal_widget",
"widget",
"zendesk",
"statusapi"
]
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
}
}
},
"put": {
"operationId": "updateExternalApplication",
"tags": [
"External Application"
],
"summary": "Update an External Application installation",
"description": "Updates External Application installation.
\nCurrently the only allowed operation is to enable or disable the app.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "external_application_slug",
"in": "path",
"description": "External Application slug",
"schema": {
"type": "string",
"enum": [
"minimal_widget",
"widget",
"zendesk",
"statusapi"
]
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
}
}
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/hubs/{subdomain}/external_applications/{external_application_slug}/reset_token": {
"put": {
"operationId": "resetExternalApplicationToken",
"tags": [
"External Application"
],
"summary": "Reset External Application token",
"description": "Resets the token for an External Application installation.
\nThis is the only way to obtain app token through Management API v3.
\nResetting the token is automatically invalidating previously used token\nand that operation is unreverisble. Can be used to quickly disable\nthe app if for example token has been compromised.\n",
"parameters": [
{
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
{
"name": "external_application_slug",
"in": "path",
"description": "External Application slug",
"schema": {
"type": "string",
"enum": [
"minimal_widget",
"widget",
"zendesk",
"statusapi"
]
},
"required": true
},
{
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"type": "object",
"description": "Returned for all External Apps except for Status API.\n",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
},
"token": {
"type": "string",
"description": "Token used when installing StatusHub application/widget.
\nOnly one token is valid at a time.
\nIn order to rotate for example compromised token reset token operation\ncan be used.\n",
"example": "0bf65c9c5aca1133e906abf80f02fd9f8066aa94"
}
}
},
{
"type": "object",
"description": "Returned for Status API which has `client_id` and `client_secret`\ninstead of a `token`.\n",
"additionalProperties": false,
"required": [],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
},
"client_id": {
"type": "string",
"description": "Client ID used for Status API application authentication",
"example": "87b4c329f0075aa5958682785bed5c37009758de"
},
"client_secret": {
"type": "string",
"description": "Client Secret used for Status API application authentication",
"example": "ba83af8c4913b4c150c0945f93cbb3377611ce41"
}
}
}
]
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid API key": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Insufficient API key role": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"type": "object"
},
"examples": {
"Invalid subdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"ApiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "X-API-KEY"
}
},
"parameters": {
"HubTypeParam": {
"name": "type",
"in": "query",
"description": "Filters Hubs by their type.\n\nPossible values:\n * `type=primary` - return only Primary Hubs,\n * `type=connected` - return only Connected Hubs.\n\nHub types:\n * Primary Hub - Independent Hub without any overlap with other\n Hubs data.
\n Associated with billing subscription.\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"schema": {
"type": "string",
"enum": [
"primary",
"connected"
],
"default": "primary"
}
},
"ParentIdParam": {
"name": "parent_id",
"in": "query",
"description": "Valid only for Connected Hubs.
\nFilters Hubs by their Primary Hub ID.\n",
"schema": {
"type": "string"
}
},
"QParam": {
"name": "q",
"in": "query",
"description": "String that filters Hubs to those containing the search string in:\n- `name`,\n- `subdomain`.\n",
"schema": {
"type": "string"
}
},
"SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"start_time"
],
"default": "position"
}
},
"SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
"PerParentSortParam": {
"name": "per_parent_sort",
"in": "query",
"description": "Valid only for Connected Hubs.
\n* `true` - sorts Connected Hubs by their parent Primary Hub position,\n* `false` - omits sorting Connected Hubs by their parent Primary Hub\n position.\n",
"schema": {
"type": "string",
"enum": [
"true",
"false"
]
}
},
"PageParam": {
"name": "page",
"in": "query",
"description": "Requested page index.",
"schema": {
"type": "integer",
"minimum": 1,
"default": 1
}
},
"PerPageParam": {
"name": "per_page",
"in": "query",
"description": "A limit on the number of records to be returned.",
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"default": 25
}
},
"ApiVersionParam": {
"name": "api_version",
"in": "query",
"description": "Api version",
"schema": {
"type": "string",
"enum": [
"V3-R1"
]
}
},
"SubdomainParam": {
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of requested Hub.",
"schema": {
"type": "string"
},
"required": true
},
"ServiceParam": {
"name": "service_id",
"in": "path",
"description": "`id` of the service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
"PrimaryHubSubdomainParam": {
"name": "subdomain",
"in": "path",
"description": "Unique `subdomain` of Primary Hub for requested Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
"common_params_QParam": {
"name": "q",
"in": "query",
"description": "Query string",
"schema": {
"type": "string"
}
},
"ConnectedSubdomainParam": {
"name": "connected_subdomain",
"in": "path",
"description": "Unique `subdomain` of Connected Hub.",
"schema": {
"type": "string"
},
"required": true
},
"AssetIDParam": {
"name": "asset_id",
"description": "Unique identifier for the asset.",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"logo",
"favicon"
]
}
},
"CreatedByMeParam": {
"name": "created_by_me",
"in": "query",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
},
"description": "Behavior:\n* `true` - filter events to only those which were created by\ncurrent user,\n* `false` - filter events to only those which were **not**\ncreated by current user,\n* `all` - don't filter events by creator.\n"
},
"IncidentDraftQueryParam": {
"name": "draft",
"in": "query",
"description": "Filters events by presence of unpublished Incident Update:\n* `true` - return only events containing at least one unpublished (draft)\nIncident Update,\n* `false` - return only events without any unpublished Incident Updates,\n* `all` - return events without filtering by draft status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"IncidentStatusParam": {
"name": "incident_types",
"in": "query",
"description": "Comma-separated names of incident types.
\nFilters incidents by status of last (including draft) update.\nExamples:\n * `incident_types=monitoring`\n * `incident_types=investigating,identified`\n\nPossible incident type values:\n * `identified`,\n * `investigating`,\n * `monitoring`,\n * `resolved`.\n\nWhen not set, do not filter incidents by type of last update.\n",
"schema": {
"type": "string"
}
},
"PublishedParam": {
"name": "published",
"in": "query",
"description": "Filter events by status of publication on Hub Page:\n* `true` - return only events published on Hub Page,\n* `false` - return only events that were not published on Hub Page.\n* `all` - don't filter events by publication status.\n",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
}
},
"UnconfirmedParam": {
"name": "unconfirmed",
"in": "query",
"description": "Filter events by state of the event:\n* `true` - return only events were published as unconfirmed on Hub Page,\n* `false` - return only events were published as confirmed on Hub Page.\n* `all` - don't filter events by unconfirmed status.\n",
"schema": {
"type": "string",
"enum": [
"true",
"false",
"all"
],
"default": "all"
}
},
"ArchivedParam": {
"name": "archived",
"in": "query",
"description": "Filters incidents by archived status:\n* `true` - return only incidents that were archived,\n* `false` - return only incidents that were not archived,\n* `all` - return incidents without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters incidents by deletion status:\n* `true` - return only incidents that were deleted,\n* `false` - return only incidents that were not deleted,\n* `all` - return incidents without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"IncidentSortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"created_at",
"start_time",
"updated_at"
],
"default": "start_time"
}
},
"IncidentSortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
"IncidentPeriodNameParam": {
"name": "period_name",
"in": "query",
"description": "Comma-separated period names.
\nFilters event by period name.\n\nExamples:\n * `period_name=current`\n * `period_name=past,current`\n\nPossible period name values:\n * `past`,\n * `current`.\n\nWhen not set, do not filter by period.\n",
"schema": {
"type": "string"
}
},
"ServiceIdsParams": {
"name": "service_ids",
"in": "query",
"description": "Comma-separated string of service ids.\n\nFilters events by at least one affected service, specified in params.\n\nExample: `service_ids=1,2,3`\n",
"schema": {
"type": "string"
}
},
"ServiceStatusesParams": {
"name": "service_statuses",
"in": "query",
"description": "Comma-separated string of service statuses names.\n\nFilters events by at least one affected service with specified status.\n\nExamples:\n* `service_statuses=degraded-performance`\n* `service_statuses=up,down`\n\nPossible incident type values:\n* `up`\n* `degraded-performance`\n* `down`\n",
"schema": {
"type": "string"
}
},
"StartTimeParam": {
"name": "start_time",
"in": "query",
"description": "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.\n",
"schema": {
"type": "string",
"default": "1900-01-01T00:00:00Z",
"format": "date-time"
}
},
"EndTimeParam": {
"name": "end_time",
"in": "query",
"description": "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.\n",
"schema": {
"type": "string",
"default": "2199-01-01T00:00:00Z",
"format": "date-time"
}
},
"EventQParam": {
"name": "q",
"in": "query",
"description": "String that filters events to those containing the search string in:\n- `title`,\n- `body`.\n",
"schema": {
"type": "string"
}
},
"ExtendParam": {
"name": "extend",
"in": "query",
"description": "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`.\n",
"schema": {
"type": "string",
"example": "flags"
}
},
"IncidentIDParam": {
"name": "incident_id",
"in": "path",
"description": "`id` of the requested incident.",
"required": true,
"schema": {
"type": "integer"
}
},
"params-ArchivedParam": {
"name": "archived",
"in": "query",
"description": "Filters incident updates by archived status:\n* `true` - return only incident updates that were archived,\n* `false` - return only incident updates that were not archived,\n* `all` - return incident updates without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"params-SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"start_time",
"created_at",
"updated_at"
],
"default": "start_time"
}
},
"params-SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
"IncidentUpdateIdParam": {
"name": "incident_update_id",
"in": "path",
"description": "`id` of the requested incident update",
"required": true,
"schema": {
"type": "integer"
}
},
"params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters templates by deletion status:\n* `true` - return only templates that were deleted,\n* `false` - return only templates that were not deleted,\n* `all` - return templates without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"IncidentTypesQueryParam": {
"name": "incident_types",
"in": "query",
"description": "Filters Incident templates by incident type value.
\nComma-separated incident types.
\nAllowed incident types:\n * investigating,\n * identified,\n * monitoring,\n * resolved.\n",
"schema": {
"type": "string"
}
},
"QParamIncident": {
"name": "q",
"in": "query",
"description": "String that filters templates to those containing the search string in:\n- `title`,\n- `body`,\n- one of the `labels`.\n",
"schema": {
"type": "string"
}
},
"QParamLabel": {
"name": "q_label",
"in": "query",
"description": "String that filters templates to those containing the search string in one of the labels.\n",
"schema": {
"type": "string"
}
},
"templates_SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at"
],
"default": "created_at"
}
},
"templates_SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
"IncidentUpdateTemplateIdParam": {
"name": "incident_template_id",
"in": "path",
"description": "`id` of the requested Incident Update Template",
"required": true,
"schema": {
"type": "integer"
}
},
"maintenance_params-ArchivedParam": {
"name": "archived",
"in": "query",
"description": "Filters maintenance events by archived status:\n* `true` - return only maintenance events that were archived,\n* `false` - return only maintenance events that were not archived,\n* `all` - return maintenance events without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"maintenance_params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters maintenance events by deletion status:\n* `true` - return only maintenance events that were deleted,\n* `false` - return only maintenance events that were not deleted,\n* `all` - return maintenance events without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"MaintenanceDraftQueryParam": {
"name": "draft",
"in": "query",
"description": "Filters events by draft status:\n* `true` - return only events that were not published yet,\n* `false` - return only events that were published,\n* `all` - return events without filtering by draft status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"MaintenancePeriodNameParam": {
"name": "period_name",
"in": "query",
"description": "Comma-separated period names.
\nFilters maintenance by period name.\n\nExamples:\n* `period_name=current`\n* `period_name=past,current`\n\nPossible period name values:\n* `past`,\n* `current`,\n* `future`.\n\nWhen not set, do not filter by period.\n",
"schema": {
"type": "string"
}
},
"MaintenanceSortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"created_at",
"start_time",
"updated_at",
"end_time"
],
"default": "start_time"
}
},
"parameters-SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
]
}
},
"MaintenanceIdParam": {
"name": "maintenance_id",
"in": "path",
"description": "`id` of the requested maintenance",
"required": true,
"schema": {
"type": "string"
}
},
"QLabelParam": {
"name": "q_label",
"in": "query",
"description": "Query label",
"schema": {
"type": "string"
}
},
"MaintenanceTemplateIdParam": {
"name": "maintenance_template_id",
"in": "path",
"description": "`id` of the requested Maintenance Template",
"required": true,
"schema": {
"type": "integer"
}
},
"subscribers_params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters subscribers by deletion status:\n* `true` - return only subscribers that were deleted,\n* `false` - return only subscribers that were not deleted,\n* `all` - return subscribers without filtering by deleted status.\n\nPlease note that this filter work on subscriber level and does not\ncheck subscriptions deletion status during filtering.
\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"params-QParam": {
"name": "q",
"in": "query",
"description": "String that filters subscribers to those containing the search string in:\n- `idp_id`.\n",
"schema": {
"type": "string",
"example": "internal-identifier-at-company.com"
}
},
"subscribers_params-SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at",
"updated_at"
],
"default": "created_at"
}
},
"SubscriberIDParam": {
"name": "subscriber_id",
"in": "path",
"description": "`id` of the subscriber",
"required": true,
"schema": {
"type": "integer"
}
},
"subscriptions_params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters subscriptions by deletion status:\n* `true` - return only subscriptions that were deleted,\n* `false` - return only subscriptions that were not deleted,\n* `all` - return subscriptions without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"DeletedAfterParam": {
"name": "deleted_after",
"in": "query",
"description": "Filters Subscriptions by the timestamp of record deletion.
\nLooks for Subscriptions deleted on or after the `deleted_after`\ntimestamp.
\nISO8601 formatted time (UTC).\n",
"schema": {
"type": "string",
"format": "date-time",
"example": "2020-09-01T08:29:00Z"
}
},
"subscriptions_params-QParam": {
"name": "q",
"in": "query",
"description": "String that filters subscriptions to those containing\nthe search string in:\n- `address`,\n- `label`.\n",
"schema": {
"type": "string"
}
},
"subscriptions_params-SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.",
"schema": {
"type": "string",
"enum": [
"created_at",
"updated_at"
],
"default": "created_at"
}
},
"SubscriptionIDParam": {
"name": "subscription_id",
"in": "path",
"description": "`id` of the subscription to be deleted",
"required": true,
"schema": {
"type": "integer"
}
},
"groups_params-ArchivedParam": {
"name": "archived",
"in": "query",
"description": "Filters groups by archived status:\n* `true` - return only groups that were archived,\n* `false` - return only groups that were not archived,\n* `all` - return groups without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"groups_params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters groups by deletion status:\n* `true` - return only groups that were deleted,\n* `false` - return only groups that were not deleted,\n* `all` - return groups without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"groups_params-QParam": {
"name": "q",
"in": "query",
"description": "String that filters groups to those containing the search string in:\n- `name`.\n",
"schema": {
"type": "string"
}
},
"groups_params-SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
"groups_params-SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
"GroupParam": {
"name": "group_id",
"in": "path",
"description": "`id` of the group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
"params-GroupParam": {
"name": "group_id",
"description": "Filters services to only those which belong to group with ID specified by `group_id`.\n",
"in": "query",
"schema": {
"type": "integer",
"minimum": 1
},
"required": false
},
"services_params-ArchivedParam": {
"name": "archived",
"in": "query",
"description": "Filters services by archived status:\n* `true` - return only services that were archived,\n* `false` - return only services that were not archived,\n* `all` - return services without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"services_params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters services by deletion status:\n* `true` - return only services that were deleted,\n* `false` - return only services that were not deleted,\n* `all` - return services without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"services_params-QParam": {
"name": "q",
"in": "query",
"description": "String that filters services to those containing the search string in:\n- `name`,\n- `custom_id`.\n",
"schema": {
"type": "string"
}
},
"PerGroupSortParam": {
"name": "per_group_sort",
"in": "query",
"description": "Alters behavior of `sort_prop`:\n- (default) If `per_group_sort` is `true` - Sort by the `sort_prop`\n in each connected group individually,\n- if `per_group_sort` is `false` - Sort by `sort_prop` globally so\n output will contain connected services ignoring the order\n of connected groups.
\n This means that connected services from same connected group\n may be interleaved by connected services from different\n connected groups.
\n One exception is `position` `sort_prop` which forces `per_group_sort`\n to be `true` regardless of actual value used in request.
\n\n If `per_group_sort` is `true` the order of connected groups\n is always determined by connected group `position`.
\n",
"schema": {
"default": true,
"type": "boolean"
}
},
"services_params-SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.
\nThe final sorting depends also on `per_group_sort` parameter:\n- (default) If `per_group_sort` is `true` - Sort by the `sort_prop`\n in each group individually,\n- if `per_group_sort` is `false` - Sort by `sort_prop` globally so\n output will contain services ignoring the order of group.
\n This means that services from same group may be interleaved by services\n from different groups.
\nOne exception is `position` `sort_prop` which forces `per_group_sort`\nto be `true` regardless of actual value used in request.
\n\nIf `per_group_sort` is `true` the order of groups is always determined\nby group `position`.
\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
"services_params-SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction inside each Group.
\nIt does not affect the order of groups which is fixed to `position`.
\nServices will be sorted by `sort_prop` inside each group individually.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
"EnabledParam": {
"name": "enabled",
"in": "query",
"description": "Filter by enabled status",
"schema": {
"type": "boolean"
}
},
"VersionParam": {
"name": "version",
"in": "query",
"description": "Filter by integration version.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"schema": {
"type": "string",
"enum": [
"v1",
"v2"
]
}
},
"SlugParam": {
"name": "integration_slug",
"in": "path",
"description": "Integration slug",
"schema": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
]
},
"required": true
},
"connected_groups_params-ArchivedParam": {
"name": "archived",
"in": "query",
"description": "Filters groups by archived status:\n* `true` - return only groups that were archived,\n* `false` - return only groups that were not archived,\n* `all` - return groups without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"connected_groups_params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters groups by deletion status:\n* `true` - return only groups that were deleted,\n* `false` - return only groups that were not deleted,\n* `all` - return groups without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"connected_groups_params-QParam": {
"name": "q",
"in": "query",
"description": "String that filters groups to those containing the search string in:\n- `name`.\n",
"schema": {
"type": "string"
}
},
"connected_groups_params-SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
"connected_groups_params-SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction.",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
"connected_groups_params-GroupParam": {
"name": "group_id",
"in": "path",
"description": "ID of Group",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
"connected_services_params-ArchivedParam": {
"name": "archived",
"in": "query",
"description": "Filters services by archived status:\n* `true` - return only services that were archived,\n* `false` - return only services that were not archived,\n* `all` - return services without filtering by archived status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"connected_services_params-DeletedParam": {
"name": "deleted",
"in": "query",
"description": "Filters services by deletion status:\n* `true` - return only services that were deleted,\n* `false` - return only services that were not deleted,\n* `all` - return services without filtering by deleted status.\n",
"schema": {
"type": "string",
"default": "false",
"enum": [
"true",
"false",
"all"
]
}
},
"connected_services_params-QParam": {
"name": "q",
"in": "query",
"description": "String that filters services to those containing the search string in:\n- `name`,\n- `custom_id`.\n",
"schema": {
"type": "string"
}
},
"connected_services_params-SortPropParam": {
"name": "sort_prop",
"in": "query",
"description": "Determines which property results should be sorted by.
\nThe final sorting depends also on `per_group_sort` parameter:\n- (default) If `per_group_sort` is `true` - Sort by the `sort_prop`\n in each connected group individually,\n- if `per_group_sort` is `false` - Sort by `sort_prop` globally so\n output will contain connected services ignoring the order\n of connected groups.
\n This means that connected services from same connected group\n may be interleaved by connected services from different\n connected groups.
\n One exception is `position` `sort_prop` which forces `per_group_sort`\n to be `true` regardless of actual value used in request.
\n\nIf `per_group_sort` is `true` the order of connected groups\nis always determined by connected group `position`.
\n",
"schema": {
"type": "string",
"enum": [
"position",
"created_at",
"updated_at"
],
"default": "position"
}
},
"connected_services_params-SortDirParam": {
"name": "sort_dir",
"in": "query",
"description": "Determines sorting direction inside each Group.
\nIt does not affect the order of groups which is fixed to `position`.
\nServices will be sorted by `sort_prop` inside each group individually.\n",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "asc"
}
},
"params-ServiceParam": {
"name": "service_id",
"in": "path",
"description": "ID of Service",
"schema": {
"type": "integer",
"minimum": 1
},
"required": true
},
"StartDate": {
"name": "start_date",
"in": "query",
"description": "Start date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
"EndDate": {
"name": "end_date",
"in": "query",
"description": "End date for uptime calculations.
\n`start_date` and `end_date` range can't be bigger than 18 months.\n",
"schema": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
}
},
"Slug": {
"name": "external_application_slug",
"in": "path",
"description": "External Application slug",
"schema": {
"type": "string",
"enum": [
"minimal_widget",
"widget",
"zendesk",
"statusapi"
]
},
"required": true
}
},
"schemas": {
"ApiVersion": {
"type": "string",
"enum": [
"V3-R1"
]
},
"PaginationData": {
"type": "object",
"required": [
"current_page",
"page_count",
"per_page",
"total"
],
"properties": {
"current_page": {
"type": "integer",
"minimum": 1,
"example": 1
},
"page_count": {
"type": "integer",
"minimum": 1,
"example": 4
},
"per_page": {
"type": "integer",
"minimum": 1,
"maximum": 100,
"example": 25
},
"total": {
"type": "integer",
"minimum": 0,
"example": 1024
}
}
},
"Id": {
"type": "integer",
"minimum": 1,
"x-autoid": true
},
"Name": {
"type": "string",
"description": "Name of the Hub.",
"example": "Example Hub"
},
"Subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"HubType": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"HubOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"subdomain",
"type"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 1
},
"name": {
"type": "string",
"description": "Name of the Hub.",
"example": "Example Hub"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
}
}
},
"ErrorResponse": {
"type": "object"
},
"CustomDomain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"ParentID": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"ProductURL": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"CreatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"UpdatedAt": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"HubDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"subdomain",
"type",
"custom_domain",
"product_url",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 3
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"HubDetailsPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
}
}
},
"StatusCounters": {
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"maxProperties": 3,
"properties": {
"up": {
"type": "integer",
"example": 0
},
"degraded-performance": {
"type": "integer",
"example": 4
},
"down": {
"type": "integer",
"example": 1
}
}
},
"CustomID": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"components-Name": {
"type": "string"
},
"ServiceStatusName": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"Details": {
"type": "object",
"additionalProperties": false,
"required": [
"service_id",
"custom_id",
"group_id",
"service_name",
"service_status",
"maintenance_ids",
"incident_ids"
],
"properties": {
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 4
},
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 5
},
"service_name": {
"type": "string"
},
"service_status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"maintenance_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 6
}
},
"incident_ids": {
"type": "array",
"items": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 7
}
}
}
},
"components-ParentID": {
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Contains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"Overview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"subdomain",
"parent_id"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 8
},
"name": {
"type": "string",
"description": "Name of the Hub.",
"example": "Example Hub"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"parent_id": {
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Contains the numerical ID of Primary Hub for current Connected Hub.
\n"
}
}
},
"Payload": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
}
}
},
"connected_hubs_Details": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"subdomain",
"custom_domain",
"parent_id",
"product_url",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 12
},
"name": {
"type": "string"
},
"subdomain": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]",
"description": "Hub subdomain.
\nHub subdomain serves two purposes:\n * In various places it is being used as Hub unique identifier\n in place of less descriptive numerical ID,\n * Forms Hub URL which without custom domain in place has a form\n of `https://{{subdomain}}.statushub.io`.\n",
"example": "company-status"
},
"custom_domain": {
"type": "string",
"nullable": true,
"description": "Alternative domain name under which the Hub can be accessed.
\nCurrently this field can be set only through a support ticket because of\nthe additional steps required like setting up the TLS certificate.\n",
"example": "status.example-company.com"
},
"parent_id": {
"nullable": true,
"type": "integer",
"minimum": 1,
"maximum": 9999,
"description": "Present only for Connected Hubs. For Primary Hubs this field is absent\nor has `null`.
\nContains the numerical ID of Primary Hub for current Connected Hub.
\n"
},
"product_url": {
"type": "string",
"nullable": true,
"description": "URL of the product or service for which current Hub is set-up for.\nAlternatively called \"Monitored site URL\" in Hub Main Settings in\nStatusHub Control Panel.\n\nUsed as a link target for Hub name or Logo in Hub Page top-bar.\n",
"example": "https://www.example-company.com/service"
},
"type": {
"type": "string",
"description": "Hub type:\n * Primary Hub\n Independent Hub without any overlap with other Hubs data.\n Associated with billing subscription,\n Can have Connected Hubs if its subscription allows it.\n * Connected Hub - Hub that shares following aspects with its Primary Hub:\n * Subset of Groups,\n * Subset of Services,\n * Events affecting the shared Services,\n * Subscription.\n\n All other data like Subscriptions and settings is independent.\n",
"example": "primary",
"enum": [
"primary",
"connected"
]
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"OKResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
},
"RestrictionUserMethodName": {
"type": "string",
"enum": [
"saml",
"google_oauth",
"global_password",
"public"
]
},
"MethodsOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"allowed_methods",
"enabled_method"
],
"properties": {
"allowed_methods": {
"type": "array",
"items": {
"type": "string",
"enum": [
"saml",
"google_oauth",
"global_password",
"public"
]
},
"example": [
"saml",
"google_oauth",
"global_password",
"public"
]
},
"enabled_method": {
"type": "string",
"enum": [
"saml",
"google_oauth",
"global_password",
"public"
]
}
}
},
"IdPMetadata": {
"type": "string",
"nullable": true,
"description": "IdP SAML metadata in XML format.\n",
"example": "\n\n...\n\n"
},
"Debug": {
"type": "boolean",
"description": "Controls verbosity of SAML error page:\n- `true` - Show detailed error message,\n- `false` - Show generic error message without details.\n"
},
"SignOutTarget": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Location where user will be redirected after successful sign-out.\n"
},
"SLO": {
"type": "boolean",
"description": "Controls if SLO should be used when signing-out from Hub:\n- `true` - SLO is enabled. This requires `SingleLogoutService`\nconfiguration to be included in `idp_metadata`,\n- `false` - SLO is not enabled.\n"
},
"URL": {
"type": "string",
"format": "uri"
},
"URI": {
"type": "string",
"format": "uri"
},
"SPData": {
"type": "object",
"additionalProperties": false,
"description": "Informational field.
\nReturns identifiers and URL that can be used to setup SAML connection.\n",
"required": [
"certificate_url",
"metadata_url",
"entity_id",
"sso_url",
"slo_url"
],
"properties": {
"certificate_url": {
"description": "URL from which StatusHub SAML public certificate can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"metadata_url": {
"description": "URL from which StatusHub SP metadata in XML format can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"entity_id": {
"description": "SP Entity ID.",
"type": "string",
"format": "uri"
},
"sso_url": {
"description": "Sign-on URL.",
"type": "string",
"format": "uri"
},
"slo_url": {
"description": "Sign-out URL. Works only if `slo` is enabled.",
"type": "string",
"format": "uri"
}
}
},
"SAMLDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled",
"idp_metadata",
"slo",
"sp_data",
"debug",
"sign_out_target"
],
"properties": {
"enabled": {
"type": "boolean"
},
"idp_metadata": {
"type": "string",
"nullable": true,
"description": "IdP SAML metadata in XML format.\n",
"example": "\n\n...\n\n"
},
"debug": {
"type": "boolean",
"description": "Controls verbosity of SAML error page:\n- `true` - Show detailed error message,\n- `false` - Show generic error message without details.\n"
},
"sign_out_target": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Location where user will be redirected after successful sign-out.\n"
},
"slo": {
"type": "boolean",
"description": "Controls if SLO should be used when signing-out from Hub:\n- `true` - SLO is enabled. This requires `SingleLogoutService`\nconfiguration to be included in `idp_metadata`,\n- `false` - SLO is not enabled.\n"
},
"sp_data": {
"type": "object",
"additionalProperties": false,
"description": "Informational field.
\nReturns identifiers and URL that can be used to setup SAML connection.\n",
"required": [],
"properties": {
"certificate_url": {
"description": "URL from which StatusHub SAML public certificate can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"metadata_url": {
"description": "URL from which StatusHub SP metadata in XML format can be downloaded\nfrom.\n",
"type": "string",
"format": "uri"
},
"entity_id": {
"description": "SP Entity ID.",
"type": "string",
"format": "uri"
},
"sso_url": {
"description": "Sign-on URL.",
"type": "string",
"format": "uri"
},
"slo_url": {
"description": "Sign-out URL. Works only if `slo` is enabled.",
"type": "string",
"format": "uri"
}
}
}
}
},
"SAMLPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"idp_metadata": {
"type": "string",
"nullable": true,
"description": "IdP SAML metadata in XML format.\n",
"example": "\n\n...\n\n"
},
"slo": {
"type": "boolean",
"description": "Controls if SLO should be used when signing-out from Hub:\n- `true` - SLO is enabled. This requires `SingleLogoutService`\nconfiguration to be included in `idp_metadata`,\n- `false` - SLO is not enabled.\n"
},
"debug": {
"nullable": true,
"type": "boolean",
"description": "Controls verbosity of SAML error page:\n- `true` - Show detailed error message,\n- `false` - Show generic error message without details.\n"
},
"sign_out_target": {
"nullable": true,
"type": "string",
"format": "uri",
"description": "Location where user will be redirected after successful sign-out.\n"
}
}
},
"Enabled": {
"type": "boolean",
"description": "State of Google OAuth authorization.
In order to enable this method the domains whitelist has to be set and enabled.\n"
},
"GoogleOAuthDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "State of Google OAuth authorization.
In order to enable this method the domains whitelist has to be set and enabled.\n"
}
}
},
"GoogleOAuthPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean",
"description": "State of Google OAuth authorization.
In order to enable this method the domains whitelist has to be set and enabled.\n"
}
}
},
"GlobalPasswordDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean"
}
}
},
"GlobalPasswordPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"password": {
"type": "string",
"minLength": 8,
"maxLength": 255
}
}
},
"DomainName": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]\\.[a-z]{2,}"
},
"DomainsWhitelist": {
"type": "array",
"items": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]\\.[a-z]{2,}"
},
"description": "Array of domain names.\n",
"example": [
"company.com",
"another-domain.com"
]
},
"DomainsWhitelistDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled",
"domains_whitelist"
],
"properties": {
"enabled": {
"type": "boolean"
},
"domains_whitelist": {
"type": "array",
"items": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]\\.[a-z]{2,}"
},
"description": "Array of domain names.\n",
"example": [
"company.com",
"another-domain.com"
]
}
}
},
"DomainsWhitelistPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"domains_whitelist": {
"type": "array",
"items": {
"type": "string",
"pattern": "[a-z0-9][a-z0-9_-]*[a-z0-9]\\.[a-z]{2,}"
},
"description": "Array of domain names.\n",
"example": [
"company.com",
"another-domain.com"
]
}
}
},
"IPV4": {
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}",
"description": "IP V4 address"
},
"IPV4CIDR": {
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\/[0-9]{1,2}",
"description": "IP V4 range in CIDR format\n"
},
"IPs": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}",
"description": "IP V4 address"
},
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\/[0-9]{1,2}",
"description": "IP V4 range in CIDR format\n"
}
]
},
"example": [
"54.210.121.161",
"144.201.96.0/21"
]
},
"NetworkDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled",
"ip_whitelist"
],
"properties": {
"enabled": {
"type": "boolean"
},
"ip_whitelist": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}",
"description": "IP V4 address"
},
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\/[0-9]{1,2}",
"description": "IP V4 range in CIDR format\n"
}
]
},
"example": [
"54.210.121.161",
"144.201.96.0/21"
]
}
}
},
"NetworkPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
},
"ip_whitelist": {
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}",
"description": "IP V4 address"
},
{
"type": "string",
"pattern": "([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\.([1-2])?\\d{1,2}\\/[0-9]{1,2}",
"description": "IP V4 range in CIDR format\n"
}
]
},
"example": [
"54.210.121.161",
"144.201.96.0/21"
]
}
}
},
"Description": {
"type": "string",
"nullable": true,
"description": "Optional description than can be visible on Hub Page.
May contain basic HTML tags.\n"
},
"URLNullable": {
"type": "string",
"format": "uri",
"nullable": true
},
"NavbarItem": {
"type": "object",
"description": "Allows to add button with link to Hub Page navbar.
Both label and URL are mandatory if any of those fields contains value.\n",
"additionalProperties": false,
"properties": {
"label": {
"type": "string",
"nullable": true,
"example": "Support portal"
},
"url": {
"example": "https://help.example-company.com",
"type": "string",
"format": "uri",
"nullable": true
}
}
},
"StatusNames": {
"type": "object",
"additionalProperties": false,
"description": "Custom labels used on Hub Page legend section.
Can be used to change default values to better match Hub Page use-case.
For example if Hub Page is set to show availability of meeting rooms then 'down' may mean 'Room is not available' and 'degraded-performance' may mean 'Room is booked'.\n",
"properties": {
"up": {
"type": "string",
"default": "Service is operating normally"
},
"degraded-performance": {
"type": "string",
"default": "Performance issues"
},
"down": {
"type": "string",
"default": "Service disruption"
}
}
},
"ISOWeek": {
"type": "boolean",
"description": "Use ISO week numbering system:\n * true - week starts on Monday,\n * false - week starts on Sunday.\n"
},
"DateFormat": {
"type": "string",
"enum": [
"EU",
"US"
],
"description": "Used date format:\n * EU - dd/mm/yyyy\n * US - mm/dd/yyyy\n"
},
"TimeFormat": {
"type": "string",
"enum": [
"12h",
"24h"
],
"description": "Used time format:\n * 12h - hh:mm AM/PM,\n * 24h - HH:mm.\n"
},
"TimeZoneName": {
"type": "string",
"description": "Default time zone used for Hub Page for visitors who haven't chosen different time zone.\n"
},
"ViewType": {
"type": "string",
"enum": [
"list",
"calendar",
"no_history",
"connected_hubs_grid"
],
"description": "History view type\n"
},
"BackgroundColor": {
"type": "string",
"description": "Custom background color in Hex format.
For Hubs still using background image, setting `background_color` will remove the background image which can then only be added through a support request.\n",
"example": "#ffffff"
},
"PlatformAlerts": {
"type": "boolean",
"description": "Show platform alerts on this Hub Page"
},
"HubsSwitcher": {
"type": "boolean",
"description": "Show Hubs switcher on this Hub Page.
This setting controls if the Hub Switcher is visible on current Hub Page.
In order to choose which Hubs are visible in Hub Switcher `show_in_hubs_switcher` should be used on respective Hubs.\n"
},
"ShowInHubsSwitcher": {
"type": "boolean",
"description": "Show this Hub inside Hubs Switcher in Hubs that show the Hubs Switcher in current account.\n"
},
"UptimeChart": {
"type": "boolean",
"description": "Shows uptime chart on hits Hub Page."
},
"Whitelabel": {
"type": "boolean",
"description": "Hide default \"Powered by StatusHub\" footer.\n"
},
"BackgroundImageURL": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "URL of image used as Hub background image.
This is a read-only field and is a legacy feature.
Once `background_color` is set, it's not possible to set the `background_image` nor `background_image_url` again in API nor in StatusHub Control Panel. Only way to set the background image is through a support request.
This field is not returned when background image is not being used.\n"
},
"AppearanceDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"description",
"favicon_url",
"logo_url",
"navbar_item",
"status_names",
"localization",
"layout"
],
"properties": {
"description": {
"type": "string",
"nullable": true,
"description": "Optional description than can be visible on Hub Page.
May contain basic HTML tags.\n"
},
"favicon_url": {
"description": "URL of Hub favicon image.",
"type": "string",
"format": "uri",
"nullable": true
},
"logo_url": {
"description": "URL of Hub logo image.",
"type": "string",
"format": "uri",
"nullable": true
},
"navbar_item": {
"type": "object",
"description": "Allows to add button with link to Hub Page navbar.
Both label and URL are mandatory if any of those fields contains value.\n",
"additionalProperties": false,
"properties": {
"label": {
"type": "string",
"nullable": true,
"example": "Support portal"
},
"url": {
"example": "https://help.example-company.com",
"type": "string",
"format": "uri",
"nullable": true
}
}
},
"status_names": {
"type": "object",
"additionalProperties": false,
"description": "Custom labels used on Hub Page legend section.
Can be used to change default values to better match Hub Page use-case.
For example if Hub Page is set to show availability of meeting rooms then 'down' may mean 'Room is not available' and 'degraded-performance' may mean 'Room is booked'.\n",
"properties": {
"up": {
"type": "string",
"default": "Service is operating normally"
},
"degraded-performance": {
"type": "string",
"default": "Performance issues"
},
"down": {
"type": "string",
"default": "Service disruption"
}
}
},
"localization": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"iso_week": {
"type": "boolean",
"description": "Use ISO week numbering system:\n * true - week starts on Monday,\n * false - week starts on Sunday.\n"
},
"date_format": {
"type": "string",
"enum": [
"EU",
"US"
],
"description": "Used date format:\n * EU - dd/mm/yyyy\n * US - mm/dd/yyyy\n"
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
],
"description": "Used time format:\n * 12h - hh:mm AM/PM,\n * 24h - HH:mm.\n"
},
"time_zone_name": {
"type": "string",
"description": "Default time zone used for Hub Page for visitors who haven't chosen different time zone.\n"
}
}
},
"layout": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"view_type": {
"type": "string",
"enum": [
"list",
"calendar",
"no_history",
"connected_hubs_grid"
],
"description": "History view type\n"
},
"background_color": {
"nullable": true,
"type": "string",
"description": "Custom background color in Hex format.
For Hubs still using background image, setting `background_color` will remove the background image which can then only be added through a support request.\n",
"example": "#ffffff"
},
"platform_alerts": {
"type": "boolean",
"description": "Show platform alerts on this Hub Page"
},
"hubs_switcher": {
"type": "boolean",
"description": "Show Hubs switcher on this Hub Page.
This setting controls if the Hub Switcher is visible on current Hub Page.
In order to choose which Hubs are visible in Hub Switcher `show_in_hubs_switcher` should be used on respective Hubs.\n"
},
"show_in_hubs_switcher": {
"type": "boolean",
"description": "Show this Hub inside Hubs Switcher in Hubs that show the Hubs Switcher in current account.\n"
},
"uptime_chart": {
"type": "boolean",
"description": "Shows uptime chart on hits Hub Page."
},
"whitelabel": {
"type": "boolean",
"description": "Hide default \"Powered by StatusHub\" footer.\n"
},
"background_image_url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "URL of image used as Hub background image.
This is a read-only field and is a legacy feature.
Once `background_color` is set, it's not possible to set the `background_image` nor `background_image_url` again in API nor in StatusHub Control Panel. Only way to set the background image is through a support request.
This field is not returned when background image is not being used.\n"
}
}
}
}
},
"AppearancePayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"description": {
"type": "string",
"nullable": true,
"description": "Optional description than can be visible on Hub Page.
May contain basic HTML tags.\n"
},
"navbar_item": {
"type": "object",
"description": "Allows to add button with link to Hub Page navbar.
Both label and URL are mandatory if any of those fields contains value.\n",
"additionalProperties": false,
"properties": {
"label": {
"type": "string",
"nullable": true,
"example": "Support portal"
},
"url": {
"example": "https://help.example-company.com",
"type": "string",
"format": "uri",
"nullable": true
}
}
},
"status_names": {
"type": "object",
"additionalProperties": false,
"description": "Custom labels used on Hub Page legend section.
Can be used to change default values to better match Hub Page use-case.
For example if Hub Page is set to show availability of meeting rooms then 'down' may mean 'Room is not available' and 'degraded-performance' may mean 'Room is booked'.\n",
"properties": {
"up": {
"type": "string",
"default": "Service is operating normally"
},
"degraded-performance": {
"type": "string",
"default": "Performance issues"
},
"down": {
"type": "string",
"default": "Service disruption"
}
}
},
"localization": {
"type": "object",
"additionalProperties": false,
"properties": {
"iso_week": {
"type": "boolean",
"description": "Use ISO week numbering system:\n * true - week starts on Monday,\n * false - week starts on Sunday.\n"
},
"date_format": {
"type": "string",
"enum": [
"EU",
"US"
],
"description": "Used date format:\n * EU - dd/mm/yyyy\n * US - mm/dd/yyyy\n"
},
"time_format": {
"type": "string",
"enum": [
"12h",
"24h"
],
"description": "Used time format:\n * 12h - hh:mm AM/PM,\n * 24h - HH:mm.\n"
},
"time_zone_name": {
"type": "string",
"description": "Default time zone used for Hub Page for visitors who haven't chosen different time zone.\n"
}
}
},
"layout": {
"type": "object",
"additionalProperties": false,
"properties": {
"view_type": {
"type": "string",
"enum": [
"list",
"calendar",
"no_history",
"connected_hubs_grid"
],
"description": "History view type\n"
},
"background_color": {
"type": "string",
"description": "Custom background color in Hex format.
For Hubs still using background image, setting `background_color` will remove the background image which can then only be added through a support request.\n",
"example": "#ffffff"
},
"platform_alerts": {
"type": "boolean",
"description": "Show platform alerts on this Hub Page"
},
"hubs_switcher": {
"type": "boolean",
"description": "Show Hubs switcher on this Hub Page.
This setting controls if the Hub Switcher is visible on current Hub Page.
In order to choose which Hubs are visible in Hub Switcher `show_in_hubs_switcher` should be used on respective Hubs.\n"
},
"show_in_hubs_switcher": {
"type": "boolean",
"description": "Show this Hub inside Hubs Switcher in Hubs that show the Hubs Switcher in current account.\n"
},
"uptime_chart": {
"type": "boolean",
"description": "Shows uptime chart on hits Hub Page."
},
"whitelabel": {
"type": "boolean",
"description": "Hide default \"Powered by StatusHub\" footer.\n"
}
}
}
}
},
"AssetPayload": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"file"
],
"properties": {
"type": {
"type": "string",
"enum": [
"logo",
"favicon"
],
"description": "Type of asset to create"
},
"file": {
"type": "string",
"format": "binary",
"description": "File to upload as asset"
}
}
},
"AssetDetails": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri"
}
}
},
"Title": {
"type": "string"
},
"Body": {
"type": "string"
},
"SilentUpdate": {
"type": "boolean",
"description": "Send notification to subscribers"
},
"PlatformAlert": {
"type": "object",
"additionalProperties": false,
"required": [
"active",
"title",
"body",
"silent"
],
"properties": {
"active": {
"type": "boolean"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"silent": {
"type": "boolean",
"description": "Send notification to subscribers"
}
}
},
"BadRequestResponse": {
"type": "object",
"additionalProperties": false,
"required": [
"message"
],
"properties": {
"message": {
"type": "string"
}
}
},
"IncidentTitle": {
"type": "string",
"description": "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."
},
"IncidentType": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"IncidentStartTime": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the `start_time` of the first (by `start_time`) Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"EventEndTime": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end. If not set it means that the event has not ended yet.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"DraftIncident": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
},
"IncidentBasicFlags": {
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [
"deleted",
"draft"
],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
}
}
},
"UnconfirmedIncident": {
"type": "boolean",
"description": "Is it an unconfirmed incident. Unconfirmed incidents are still visible on Hub Page.\n"
},
"IncidentExtendedFlags": {
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [
"archived",
"deleted",
"draft",
"follow_up",
"published",
"unconfirmed"
],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
},
"follow_up": {
"type": "boolean",
"description": "Is it a follow-up incident."
},
"published": {
"type": "boolean",
"description": "Event was published on Hub Page."
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed incident. Unconfirmed incidents are still visible on Hub Page.\n"
}
}
},
"IncidentOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"last_incident_type",
"start_time",
"end_time",
"flags"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 13
},
"title": {
"type": "string",
"description": "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."
},
"last_incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the `start_time` of the first (by `start_time`) Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end. If not set it means that the event has not ended yet.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
},
"follow_up": {
"type": "boolean",
"description": "Is it a follow-up incident."
},
"published": {
"type": "boolean",
"description": "Event was published on Hub Page."
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed incident. Unconfirmed incidents are still visible on Hub Page.\n"
}
}
}
]
}
}
},
"EventTitle": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"EventStartTimeParam": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"ServiceStatusesPayload": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"common_Body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"common_SilentUpdate": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"IncidentState": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
},
"OriginalIncidentID": {
"type": "integer",
"description": "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.\n",
"minimum": 1,
"example": 102
},
"IncidentPayload": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"start_time",
"incident_type",
"service_statuses"
],
"properties": {
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
},
"original_incident_id": {
"type": "integer",
"description": "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.\n",
"minimum": 1,
"example": 102
}
}
},
"Author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"IncidentDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"author",
"title",
"created_at",
"start_time",
"updated_at",
"end_time",
"flags"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 15
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"title": {
"type": "string",
"description": "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_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the `start_time` of the first (by `start_time`) Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end. If not set it means that the event has not ended yet.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Does this incident has any unpublished updates (drafts)."
},
"follow_up": {
"type": "boolean",
"description": "Is it a follow-up incident."
},
"published": {
"type": "boolean",
"description": "Event was published on Hub Page."
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed incident. Unconfirmed incidents are still visible on Hub Page.\n"
}
}
}
]
}
}
},
"IncidentUpdateTitle": {
"type": "string",
"description": "Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.\n"
},
"IncidentUpdateStartTime": {
"type": "string",
"format": "date-time",
"description": "Timestamps of a Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"EventState": {
"type": "string",
"enum": [
"undefined",
"draft",
"unconfirmed",
"published"
],
"description": "Event state",
"example": "published"
},
"IncidentUpdateBasicFlags": {
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [
"deleted",
"draft"
],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
}
}
},
"IncidentUpdateExtendedFlags": {
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [
"archived",
"deleted",
"draft",
"silent",
"unconfirmed"
],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed Incident Update. Unconfirmed can only be a first Incident Update of an Incident. Unconfirmed Incident Updates are still visible on Hub Page.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Incident Update.
Silent event does not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
}
}
},
"IncidentUpdateOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"incident_type",
"state"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 16
},
"title": {
"type": "string",
"description": "Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.\n"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamps of a Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"state": {
"type": "string",
"enum": [
"undefined",
"draft",
"unconfirmed",
"published"
],
"description": "Event state",
"example": "published"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed Incident Update. Unconfirmed can only be a first Incident Update of an Incident. Unconfirmed Incident Updates are still visible on Hub Page.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Incident Update.
Silent event does not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
}
}
}
]
}
}
},
"IncidentUpdateTitleParam": {
"type": "string",
"description": "Title of this update.
Can contain only plain text.
Setting `title` to value different from current title of Incident may result in changing of Incident title.
Incident title equals to title of latest (by `start_time`) published (not draft) Incident Update `title`.\n"
},
"ServiceStatusesCreatePayload": {
"type": "array",
"description": "Describes affected services and their statuses.
This parameter is required unless `incident_type` is `resolved`, in which case it is forbidden because resolving an incident automatically sets all affected services to `up` status for this incident.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"IncidentUpdateCreatePayload": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"start_time",
"incident_type"
],
"properties": {
"title": {
"type": "string",
"description": "Title of this update.
Can contain only plain text.
Setting `title` to value different from current title of Incident may result in changing of Incident title.
Incident title equals to title of latest (by `start_time`) published (not draft) Incident Update `title`.\n"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.
This parameter is required unless `incident_type` is `resolved`, in which case it is forbidden because resolving an incident automatically sets all affected services to `up` status for this incident.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
}
}
},
"ServiceStatuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"IncidentUpdateDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"author",
"body",
"title",
"created_at",
"start_time",
"updated_at",
"incident_type",
"service_statuses",
"state"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 25
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"title": {
"type": "string",
"description": "Title of this update. May be different from current incident title.
Incident title may be changed during the duration of incident and therefore some updates may reflect previous title.\n"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"start_time": {
"type": "string",
"format": "date-time",
"description": "Timestamps of a Incident Update.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services has been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Incident Update a draft - meaning it wasn't published on a Hub Page.\n"
},
"unconfirmed": {
"type": "boolean",
"description": "Is it an unconfirmed Incident Update. Unconfirmed can only be a first Incident Update of an Incident. Unconfirmed Incident Updates are still visible on Hub Page.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Incident Update.
Silent event does not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
}
}
}
]
}
}
},
"ServiceStatusesUpdatePayload": {
"type": "array",
"description": "Describes affected services and their statuses.
This parameter is forbidden if `incident_type` is `resolved` because resolving an incident automatically sets all affected services to `up` status for this incident.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"IncidentUpdateUpdatePayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Title of this update.
Can contain only plain text.
Setting `title` to value different from current title of Incident may result in changing of Incident title.
Incident title equals to title of latest (by `start_time`) published (not draft) Incident Update `title`.\n"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
Can't be in future.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"incident_type": {
"type": "string",
"description": "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.\n",
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
],
"example": "investigating"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.
This parameter is forbidden if `incident_type` is `resolved` because resolving an incident automatically sets all affected services to `up` status for this incident.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Incident or Incident Update:\n\n* `draft` - Not published on Hub Page,\n* `unconfirmed` - Published on Hub Page but marked as unconfirmed,\n* `published` - Published on Hub Page.\n",
"default": "published",
"example": "published",
"nullable": true,
"enum": [
"draft",
"unconfirmed",
"published"
]
}
}
},
"templates_Title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"Label": {
"type": "string"
},
"Labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"Silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
},
"Flags": {
"type": "object",
"additionalProperties": false,
"required": [
"deleted",
"silent"
],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"templates_IncidentType": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"IncidentUpdateTemplateOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"labels",
"flags",
"incident_type"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 29
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
}
}
},
"TitleParam": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"BodyParam": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"LabelsParam": {
"type": "array",
"items": {
"type": "string"
},
"description": "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\"]`.\n"
},
"IncidentUpdateTemplatePayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "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\"]`.\n"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"silent_update": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"templates_Body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"IncidentUpdateTemplateDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"labels",
"flags",
"incident_type",
"body",
"created_at",
"updated_at",
"author",
"service_statuses"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 38
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"incident_type": {
"type": "string",
"nullable": true,
"enum": [
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
},
"StartTime": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"EndTime": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"MaintenanceBasicFlags": {
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [
"deleted",
"draft"
],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
}
}
},
"SuppressEvents": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"MaintenanceExtendedFlags": {
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [
"archived",
"deleted",
"draft",
"published",
"suppress_events",
"silent",
"recurring_placeholder"
],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services have been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
},
"published": {
"type": "boolean",
"description": "Was this Maintenance event published on a Hub Page.\n"
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Maintenance.
Silent events do not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
},
"recurring_placeholder": {
"type": "boolean",
"description": "Recurring maintenance schedule utilize so called Placeholder Events that are visible on Hub Page and contains all of the info as normal Maintenance events would.
However those placeholders are not fully fledged Maintenance events and some operations may not be available for those placeholder events. For example, such events when deleted are permanently removed and are not a subject to undelete.
Placeholder events are converted to normal (full) Maintenance events when either maintenance will start soon or notifications needs to be send for this event. After converting Placeholder Maintenance to normal Maintenance, such event behaves like any other normal Maintenance event.\n"
}
}
},
"MaintenanceOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"start_time",
"end_time",
"flags"
],
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services have been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
},
"published": {
"type": "boolean",
"description": "Was this Maintenance event published on a Hub Page.\n"
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Maintenance.
Silent events do not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
},
"recurring_placeholder": {
"type": "boolean",
"description": "Recurring maintenance schedule utilize so called Placeholder Events that are visible on Hub Page and contains all of the info as normal Maintenance events would.
However those placeholders are not fully fledged Maintenance events and some operations may not be available for those placeholder events. For example, such events when deleted are permanently removed and are not a subject to undelete.
Placeholder events are converted to normal (full) Maintenance events when either maintenance will start soon or notifications needs to be send for this event. After converting Placeholder Maintenance to normal Maintenance, such event behaves like any other normal Maintenance event.\n"
}
}
}
]
}
}
},
"StateParam": {
"type": "string",
"description": "State of Maintenance event:\n\n* `draft` - Not published on Hub Page.\n Draft will result in draft notifications being sent\n to Team Members,\n* `published` - Published on Hub Page.\n",
"default": "published",
"nullable": true,
"enum": [
"draft",
"published"
]
},
"EventRepeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"EventNotificationsParam": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.
Those additional notifications can be used for sending automated reminder notification to subscriptions about upcoming or just finished maintenance.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\nNot all combinations are possible for\n`offset_type` and `offset_in_min`:\n\nAllowed for `start`:\n* -129600 - 90 days,\n* -86400 - 60 days,\n* -43200 - 30 days,\n* -10080 - 7 days,\n* -2880 - 2 days,\n* -1440 - 1 days,\n* -120 - 2 hours,\n* -60 - 1 hour,\n* -30 - 30 minutes,\n* -15 - 15 minutes,\n* -5 - 5 minutes,\n* 0 - at event start (`start_time`).\n\nAllowed for `end`:\n* 0 - at event end (`end_time`).\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"MaintenancePayload": {
"type": "object",
"additionalProperties": false,
"required": [
"title",
"start_time",
"end_time",
"service_statuses"
],
"properties": {
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Maintenance event:\n\n* `draft` - Not published on Hub Page.\n Draft will result in draft notifications being sent\n to Team Members,\n* `published` - Published on Hub Page.\n",
"default": "published",
"nullable": true,
"enum": [
"draft",
"published"
]
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.
Those additional notifications can be used for sending automated reminder notification to subscriptions about upcoming or just finished maintenance.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\nNot all combinations are possible for\n`offset_type` and `offset_in_min`:\n\nAllowed for `start`:\n* -129600 - 90 days,\n* -86400 - 60 days,\n* -43200 - 30 days,\n* -10080 - 7 days,\n* -2880 - 2 days,\n* -1440 - 1 days,\n* -120 - 2 hours,\n* -60 - 1 hour,\n* -30 - 30 minutes,\n* -15 - 15 minutes,\n* -5 - 5 minutes,\n* 0 - at event start (`start_time`).\n\nAllowed for `end`:\n* 0 - at event end (`end_time`).\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
}
}
},
"EventNotifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"MaintenanceDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"author",
"created_at",
"title",
"body",
"start_time",
"end_time",
"service_statuses",
"flags",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Event was archived for example because all affected services have been deleted or archived.
Archived events are read-only.\n"
},
"deleted": {
"type": "boolean",
"description": "Event has been deleted."
},
"draft": {
"type": "boolean",
"description": "Is this Maintenance a draft - meaning, it wasn't published on a Hub Page.\n"
},
"published": {
"type": "boolean",
"description": "Was this Maintenance event published on a Hub Page.\n"
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"silent": {
"type": "boolean",
"description": "Is it a silent Maintenance.
Silent events do not result in notifications being sent to subscriptions.
Does not impact draft notifications for Team Members.\n"
},
"recurring_placeholder": {
"type": "boolean",
"description": "Recurring maintenance schedule utilize so called Placeholder Events that are visible on Hub Page and contains all of the info as normal Maintenance events would.
However those placeholders are not fully fledged Maintenance events and some operations may not be available for those placeholder events. For example, such events when deleted are permanently removed and are not a subject to undelete.
Placeholder events are converted to normal (full) Maintenance events when either maintenance will start soon or notifications needs to be send for this event. After converting Placeholder Maintenance to normal Maintenance, such event behaves like any other normal Maintenance event.\n"
}
}
}
]
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"UpdateMaintenancePayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Title of event.
Can contain only plain text. HTML tags and other forms of formatting are not allowed.\n",
"example": "Title of the event"
},
"start_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event start.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"end_time": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "Timestamp of event end.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"body": {
"type": "string",
"default": "",
"example": "Message for an event or event update.
\nMay contain basic HTML tags.\n"
},
"silent": {
"type": "boolean",
"description": "When `true` notifications are not being sent to subscribers.
Does not impact draft notifications for Team Members.\n",
"default": false
},
"state": {
"type": "string",
"description": "State of Maintenance event:\n\n* `draft` - Not published on Hub Page.\n Draft will result in draft notifications being sent\n to Team Members,\n* `published` - Published on Hub Page.\n",
"default": "published",
"nullable": true,
"enum": [
"draft",
"published"
]
},
"suppress_events": {
"type": "boolean",
"description": "When `true` for the duration of maintenance all Incidents and Incident Updates created through automation (API, integrations) will not be published.
Depending on configuration such Incidents will be either:\n * saved as draft,\n * ignored.\n"
},
"event_repeat": {
"type": "object",
"nullable": true,
"description": "Describes recurring maintenance schedules.\n",
"properties": {
"interval": {
"type": "string",
"description": "How frequent should the event be repeated.\n",
"enum": [
"day",
"week",
"two_weeks",
"month",
"year"
]
},
"interval_options": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for some of the `interval` values:
\nFor `day`: `enabled_days`.
\nFor `month`: `type`.\n",
"properties": {
"enabled_days": {
"type": "string",
"description": "Valid only for `\"interval\": \"day\"`.
\nComma-separated list of enabled days indexes (0-6).
\n * 0 - Sunday,\n * 1 - Monday,\n * 2 - Tuesday,\n * 3 - Wednesday,\n * 4 - Thursday,\n * 5 - Friday,\n * 6 - Saturday.\n",
"example": "0,2,5"
},
"type": {
"type": "string",
"description": "Valid only for `\"interval\": \"month\"`.
Month interval type:\n * `day_of_month` - Repeat on same day of month. For example on\n every 5th of the month,\n * `day_of_week` - Repeat on the same occurrence of nth day of the\n week. For example on 2nd Saturday of the month.\n",
"enum": [
"day_of_month",
"day_of_week"
],
"default": "day_of_month"
}
}
},
"end_on": {
"type": "string",
"format": "date-time",
"nullable": true,
"description": "When should the repeating of recurring maintenance event stop.
If not set, recurring schedule will continue. ISO8601 formatted time (UTC)\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"event_notifications": {
"type": "array",
"description": "Describes additional notifications to be sent at specific offset from maintenance start or end.\n",
"items": {
"type": "object",
"properties": {
"offset_in_min": {
"type": "integer",
"description": "Negative value of offset in minutes.\n",
"maximum": 0,
"example": -60,
"enum": [
-129600,
-86400,
-43200,
-10080,
-2880,
-1440,
-120,
-60,
-30,
-15,
-5,
0
]
},
"offset_type": {
"type": "string",
"description": "EventNotification delivery offset type:\n* `start` - from maintenance start time,\n* `end` - from maintenance end time.
\n",
"default": "start",
"enum": [
"start",
"end"
]
}
}
}
},
"recurring": {
"type": "object",
"description": "Used only for Maintenance events being a part of Recurring Maintenance Schedule. Instructs API how to handle edit of an event that is repeating.\n",
"additionalProperties": false,
"properties": {
"update_following": {
"type": "boolean",
"description": "When `true` modifies currently updated event as well as all following events being a part of the same Recurring Maintenance Schedule.
When `false` modifies only currently updated event. Following events in same Recurring Maintenance Schedule remains unchanged.\n"
}
}
}
}
},
"UpdateRecurringEventsPayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"recurring": {
"type": "object",
"required": [
"update_following"
],
"additionalProperties": false,
"properties": {
"update_following": {
"type": "boolean"
}
}
}
}
},
"Duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.\n"
},
"MaintenanceTemplateOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"labels",
"flags",
"duration"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 51
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.\n"
}
}
},
"DurationParam": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.
Maximum allowed value is 99h:59min (5999 minutes).\n"
},
"MaintenanceTemplatePayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "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.\n"
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.
Maximum allowed value is 99h:59min (5999 minutes).\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "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\"]`.\n"
},
"service_statuses": {
"type": "array",
"description": "Describes affected services and their statuses.\n",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"service_id": {
"type": "integer",
"example": 1234
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
}
}
}
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"MaintenanceTemplateDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"title",
"labels",
"flags",
"duration",
"body",
"created_at",
"updated_at",
"author",
"service_statuses"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 60
},
"title": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `title` set will ignore event `title` when applied.\n"
},
"labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of labels for this template."
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Is this template deleted.
Deleted templates can't be used when creating or updating events.\n"
},
"silent": {
"type": "boolean",
"nullable": true,
"description": "Controls `silent` parameter value when applying the template:\n* `true` - Set event `silent` parameter as `true`,\n* `false` - Set event `silent` parameter as `false`,\n* `null` - Do not set event `silent` parameter.\n"
}
}
},
"duration": {
"type": "integer",
"nullable": true,
"minimum": 1,
"maximum": 5999,
"description": "Duration of maintenance in minutes.\n"
},
"body": {
"type": "string",
"nullable": true,
"description": "Title of event.
Templates without `body` set will ignore event `body` when applied.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"author": {
"type": "string",
"nullable": true,
"description": "Author email"
},
"service_statuses": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 61
},
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 62
},
"service_name": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"up",
"degraded-performance",
"down"
],
"example": "down"
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 63
},
"group_name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
}
}
}
}
}
}
},
"IDPID": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"BasicFlags": {
"type": "object",
"additionalProperties": false,
"required": [
"deleted"
],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscriber has been deleted.",
"example": false
}
}
},
"subscribers_Overview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"idp_id",
"flags"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 64
},
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscriber has been deleted.",
"example": false
}
}
}
}
},
"Address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"SubscriptionMethodName": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"ServicesSelectionParam": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"Configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"components-Label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"LessVerbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"Protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
},
"SubscriberIDParam": {
"type": "integer",
"description": "`id` of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.\n",
"example": 9
},
"CreatePayload": {
"type": "object",
"additionalProperties": false,
"required": [
"address",
"method_name",
"services_selection"
],
"properties": {
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
},
"subscriber_id": {
"type": "integer",
"description": "`id` of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.\n",
"example": 9
}
}
},
"subscribers_CreatePayload": {
"type": "object",
"additionalProperties": false,
"required": [
"subscriptions"
],
"properties": {
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"subscriptions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"address",
"method_name",
"services_selection"
],
"properties": {
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
},
"subscriber_id": {
"type": "integer",
"description": "`id` of the Subscriber. If not provided, StatusHub will create new, empty Subscriber record.\n",
"example": 9
}
}
},
"minItems": 1
}
}
},
"subscribers_Details": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"idp_id",
"flags",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 67
},
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscriber has been deleted.",
"example": false
}
}
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"UpdatePayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"idp_id": {
"type": "string",
"description": "Identifier used to authenticate the subscriber for private Hubs that use authorization method providing user ID. For example for SAML protected Hubs.\n",
"nullable": true,
"example": "internal-identifier-at-company.com"
}
}
},
"ServiceSelectionOverview": {
"type": "object",
"additionalProperties": false,
"required": [
"all"
],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
}
}
},
"components-BasicFlags": {
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [
"deleted"
],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
"ExtendedFlags": {
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [
"deleted",
"less_verbose",
"credentials",
"protected"
],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
},
"subscriptions_Overview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"address",
"method_name",
"subscriber_id",
"services_selection",
"flags"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 78
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 79
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
}
}
},
"ServiceSelectionItem": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"group_name",
"archived"
],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
},
"ServiceSelectionDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"all",
"services"
],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"subscriptions_Details": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"address",
"method_name",
"subscriber_id",
"services_selection",
"label",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 86
},
"address": {
"type": "string",
"description": "Address for a subscription. Exact meaning depends on method name:\n* email - email address,\n* sms - phone number,\n* webhook - URL,\n* slack - Slack Incoming Webhook URL,\n* teams - MS Teams Incoming Webhook URL.\n",
"example": "example@statushub.com"
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"method_name": {
"type": "string",
"enum": [
"email",
"sms",
"webhook",
"slack",
"teams"
],
"example": "email"
},
"subscriber_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 87
},
"services_selection": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"all": {
"type": "boolean",
"description": "Is this subscription subscribed to all services in the Hub.
Subscription subscribed to all services will be notified about events affecting the services even if service was added after the subscription has been created.
If subscription is not subscribed to all services then any notification affecting only newly added service will not be sent to this subscription.\n",
"example": true
},
"services": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"id": {
"type": "integer",
"example": 1234
},
"name": {
"type": "string",
"example": "Service name"
},
"group_name": {
"type": "string",
"example": "Group name"
},
"archived": {
"type": "boolean",
"example": false
}
}
}
}
}
},
"flags": {
"oneOf": [
{
"type": "object",
"title": "Basic flags",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
}
}
},
{
"type": "object",
"title": "Extended flags",
"description": "Returned when passing `extend=flags` in request query params.\n",
"additionalProperties": false,
"required": [],
"properties": {
"deleted": {
"type": "boolean",
"description": "Subscription has been deleted.",
"example": false
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"credentials": {
"type": "boolean",
"description": "Subscription use additional credentials in request headers.
Valid only for webhook subscriptions.\n",
"example": false
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
}
]
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
}
}
},
"subscriptions_UpdatePayload": {
"type": "object",
"additionalProperties": false,
"required": [
"services_selection"
],
"properties": {
"services_selection": {
"type": "object",
"additionalProperties": false,
"description": "\"all\" has precedence over \"services\". If \"all\" is false, \"services\" can't be empty. If \"all\" is true, \"services\" value is being ignored\n",
"properties": {
"all": {
"type": "boolean",
"description": "`true` it means that Subscription is subscribed to all current and future Services in current Hub.
When `false`, `service_ids` cannot be empty.\n",
"default": false,
"example": false
},
"service_ids": {
"type": "array",
"description": "StatusHub ID's of services to which Subscription should be subscribed to.
If contains same values as all Service ID's for current Hub, it automatically implies `all` to be `true` so subscribing to all current and future Services for current Hub.\n",
"items": {
"type": "integer"
},
"example": [
449,
24221,
2
]
}
}
},
"configuration": {
"type": "object",
"additionalProperties": false,
"description": "Additional configuration for this method name or this Subscription\n",
"properties": {
"short_messages": {
"type": "boolean",
"description": "Valid only for Slack subscriptions.
\nValues explanation:\n* `false` - this subscription will receive regular notification payload,\n* `true` - this subscription will receive smaller version\n of notifications with less data.\n For example affected services list will not be included.\n",
"default": false
},
"content_type": {
"type": "string",
"enum": [
"application/x-www-form-urlencoded",
"application/json"
],
"description": "Valid only for webhook subscriptions.
\nSpecifies what content type will be used to encode\nnotification payload.\n",
"default": "application/x-www-form-urlencoded"
}
},
"example": {
"content_type": "application/json"
}
},
"label": {
"type": "string",
"nullable": true,
"description": "Additional information to add better meaning for subscription.
Typically used to add responsible person name or team to SMS or URL-based subscriptions where address alone is not enough to know who is receiving the notifications.
Not available for email subscriptions.\n",
"example": "Responsible person name"
},
"less_verbose": {
"type": "boolean",
"description": "Subscription will receive the minimum number of notifications per incident - typically first and final.\n",
"default": false,
"example": true
},
"protected": {
"type": "boolean",
"description": "Subscription is protected which means it doesn't have the ability of self-service like editing the services list or subscription options as well as doesn't have the ability to self-unsubscribe.
Typically used for group email subscriptions where without this option, any member of an email group could use unsubscribe through the unsubscribe link sent in every notification. And as a result the whole group would stop receiving notifications.\n",
"default": false,
"example": false
}
}
},
"components-Flags": {
"type": "object",
"additionalProperties": false,
"required": [
"deleted"
],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
},
"groups_Overview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"flags"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 100
},
"name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
},
"groups_Payload": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
}
}
},
"groups_Details": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"name",
"flags",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 101
},
"name": {
"type": "string"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this group archived.
Events affecting only the services in archived group are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this group deleted.
Events affecting only the services in deleted group are not visible on Hub Page, even with direct event link.\n"
}
}
}
}
},
"services_components-Flags": {
"type": "object",
"additionalProperties": false,
"required": [
"deleted"
],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
},
"services_Overview": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"custom_id",
"name",
"group_id",
"flags"
],
"properties": {
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 102
},
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 103
},
"name": {
"type": "string"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
},
"components-Description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"PublicName": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
},
"services_Payload": {
"type": "object",
"additionalProperties": false,
"required": [
"group_id",
"name"
],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
}
}
},
"Token": {
"type": "string",
"description": "Unique token value that is being used to connect external integrations to StatusHub.
Typically all integration URLs are using the `token` value so knowing the `token` value allows to construct various integrations URLs programmatically.\n"
},
"services_Details": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"custom_id",
"name",
"group_id",
"flags",
"description",
"token",
"created_at",
"updated_at",
"public_name"
],
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 106
},
"id": {
"type": "integer",
"minimum": 1,
"x-autoid": true,
"example": 107
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
},
"token": {
"type": "string",
"description": "Unique token value that is being used to connect external integrations to StatusHub.
Typically all integration URLs are using the `token` value so knowing the `token` value allows to construct various integrations URLs programmatically.\n"
},
"created_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of record creation.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "Timestamp of last modification of record.
ISO8601 formatted time (UTC).\n",
"example": "2020-09-01T08:29:00Z"
},
"flags": {
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"archived": {
"type": "boolean",
"description": "Is this service archived.
Events affecting only the archived services are still visible on Hub Page with direct event link."
},
"deleted": {
"type": "boolean",
"description": "Is this service deleted.
Events affecting only the deleted services are still visible on Hub Page with direct event link.\n"
}
}
}
}
},
"services_UpdatePayload": {
"type": "object",
"additionalProperties": false,
"properties": {
"custom_id": {
"type": "string",
"description": "`custom_id` is a property that can be used to assign an external identifier to a service. This identifier can be used, for example, to synchronize monitored entities with services in StatusHub.
`custom_id` has to be unique within the scope of a Hub.\n",
"nullable": true
},
"description": {
"type": "string",
"description": "`description` can be used to add more information describing the service on a Hub Page. Description is visible inside a tooltip in a Hub Page.\n",
"nullable": true
},
"group_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true
},
"name": {
"type": "string"
},
"public_name": {
"type": "string",
"description": "`public_name` is an optional name that can be used to show different name for visitors of Hub Page and subscribers.
Typical use-case is to use `name` describing customer or contractor name so members using StatusHub Control Panel can distinguish the services easily and use `public_name` with generic or obfuscated name to not disclose the actual name of customer or subcontractor especially on public Hubs.\n",
"nullable": true
}
}
},
"components-Enabled": {
"type": "boolean",
"description": "Is integration enabled on this service\n",
"example": true
},
"Slug": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
],
"example": "generic_hook_v2"
},
"Version": {
"type": "string",
"description": "Version of the integration.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"enum": [
"v1",
"v2"
],
"example": "v2"
},
"integrations_Overview": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled",
"slug",
"version"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Is integration enabled on this service\n",
"example": true
},
"slug": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
],
"example": "generic_hook_v2"
},
"version": {
"type": "string",
"description": "Version of the integration.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"enum": [
"v1",
"v2"
],
"example": "v2"
}
}
},
"components-URL": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Except for Pingdom integration, `url` is unique per-Service URL that\nshould be used to connect 3rd party service to StatusHub Service.
\nBehavior of this field varies between `v1` and `v2` integrations:\n- For `v1` integrations, this URL share same token part between\n integrations and `url` is never blank,\n- For `v2` integrations, each integration may use different token.
\n `url` is blank if `v2` integration is not enabled.\n",
"example": "https://app.statushub.io/hooks/generic_hook_v2?token=a18331da-19a5-46f1-8bfa-06a6a31f1d10"
},
"integrations_Details": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled",
"slug",
"version",
"url"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Is integration enabled on this service\n",
"example": true
},
"slug": {
"type": "string",
"enum": [
"generic_hook",
"generic_hook_v2",
"ilert",
"isdownapp",
"new_relic",
"opsgenie",
"pager_duty",
"pingdom",
"site_247",
"statusgator",
"still_alive",
"uptime_robot",
"uptrends",
"victor_ops"
],
"example": "generic_hook_v2"
},
"version": {
"type": "string",
"description": "Version of the integration.
\nCurrently available versions:\n- `v1` - basic integrations available in StatusHub for long time,\n- `v2` - more capable integrations. All newly introduced\nintegrations will be added in `v2` version.\n",
"enum": [
"v1",
"v2"
],
"example": "v2"
},
"url": {
"type": "string",
"format": "uri",
"nullable": true,
"description": "Except for Pingdom integration, `url` is unique per-Service URL that\nshould be used to connect 3rd party service to StatusHub Service.
\nBehavior of this field varies between `v1` and `v2` integrations:\n- For `v1` integrations, this URL share same token part between\n integrations and `url` is never blank,\n- For `v2` integrations, each integration may use different token.
\n `url` is blank if `v2` integration is not enabled.\n",
"example": "https://app.statushub.io/hooks/generic_hook_v2?token=a18331da-19a5-46f1-8bfa-06a6a31f1d10"
}
}
},
"EnabledParam": {
"type": "boolean",
"description": "Should integration be enabled on this service\n",
"example": true
},
"integrations_UpdatePayload": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Should integration be enabled on this service\n",
"example": true
}
}
},
"connected_services_Payload": {
"type": "object",
"additionalProperties": false,
"required": [
"service_id"
],
"properties": {
"service_id": {
"type": "integer",
"minimum": 1,
"x-autoid": true
}
}
},
"Date": {
"type": "string",
"format": "date",
"description": "Full-date notation as defined by RFC 3339, section 5.6.\n",
"example": "2025-01-01"
},
"UptimeValue": {
"type": "number",
"description": "Uptime value for the requested period. Value is between 0.0 and 1.0, where 0 means no uptime and 1 means 100% uptime.
Uptime value is always rounded down.\n",
"minimum": 0,
"maximum": 1,
"example": 0.9995
},
"UptimeDetails": {
"type": "object",
"additionalProperties": false,
"required": [
"uptime"
],
"properties": {
"uptime": {
"type": "number",
"description": "Uptime value for the requested period. Value is between 0.0 and 1.0, where 0 means no uptime and 1 means 100% uptime.
Uptime value is always rounded down.\n",
"minimum": 0,
"maximum": 1,
"example": 0.9995
}
}
},
"DailyUptimeDetails": {
"type": "object",
"additionalProperties": {
"type": "number",
"description": "Uptime value for the requested period. Value is between 0.0 and 1.0, where 0 means no uptime and 1 means 100% uptime.
Uptime value is always rounded down.\n",
"minimum": 0,
"maximum": 1,
"example": 0.9995
},
"example": {
"2023-01-01": 0.9995,
"2023-01-02": 1,
"2023-01-03": 0.68351,
"2023-01-04": 0.99999,
"2023-01-05": 1
}
},
"external_applications_components-Enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"components-Slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
},
"external_applications_Overview": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled",
"slug"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
}
}
},
"external_applications_Details": {
"type": "object",
"additionalProperties": false,
"required": [
"enabled",
"slug"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
}
}
},
"external_applications_Payload": {
"type": "object",
"additionalProperties": false,
"properties": {
"enabled": {
"type": "boolean"
}
}
},
"components-Token": {
"type": "string",
"description": "Token used when installing StatusHub application/widget.
\nOnly one token is valid at a time.
\nIn order to rotate for example compromised token reset token operation\ncan be used.\n",
"example": "0bf65c9c5aca1133e906abf80f02fd9f8066aa94"
},
"DetailsWithToken": {
"type": "object",
"description": "Returned for all External Apps except for Status API.\n",
"additionalProperties": false,
"required": [
"enabled",
"slug",
"token"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
},
"token": {
"type": "string",
"description": "Token used when installing StatusHub application/widget.
\nOnly one token is valid at a time.
\nIn order to rotate for example compromised token reset token operation\ncan be used.\n",
"example": "0bf65c9c5aca1133e906abf80f02fd9f8066aa94"
}
}
},
"ClientID": {
"type": "string",
"description": "Client ID used for Status API application authentication",
"example": "87b4c329f0075aa5958682785bed5c37009758de"
},
"ClientSecret": {
"type": "string",
"description": "Client Secret used for Status API application authentication",
"example": "ba83af8c4913b4c150c0945f93cbb3377611ce41"
},
"StatusApiDetailsWithCredentials": {
"type": "object",
"description": "Returned for Status API which has `client_id` and `client_secret`\ninstead of a `token`.\n",
"additionalProperties": false,
"required": [
"enabled",
"slug",
"client_id",
"client_secret"
],
"properties": {
"enabled": {
"type": "boolean",
"description": "Status of app:\n- `enabled` - Application installations will work for as long as the\n used token is valid,\n- `disabled` - Application installations will not work even if used token\n is valid.\n",
"example": true
},
"slug": {
"type": "string",
"description": "External Application slug",
"example": "widget"
},
"client_id": {
"type": "string",
"description": "Client ID used for Status API application authentication",
"example": "87b4c329f0075aa5958682785bed5c37009758de"
},
"client_secret": {
"type": "string",
"description": "Client Secret used for Status API application authentication",
"example": "ba83af8c4913b4c150c0945f93cbb3377611ce41"
}
}
}
},
"examples": {
"InvalidAPIKey": {
"description": "Returned when API key is invalid.\n",
"value": {
"message": [
"user_unauthorized"
]
}
},
"InsufficientAPIKeyRole": {
"description": "Returned when API key overrides Member role to not powerful enough to perform requested operation.\n",
"value": {
"message": "not authorized"
}
},
"InvalidSubdomain": {
"description": "Returned when `subdomain` is invalid. Same error is returned when there is no Hub with such subdomain as well as when Hub with such subdomain exists but current member does not have sufficient access to it.\n",
"value": {
"message": "record not found"
}
},
"MalformedJSON": {
"description": "Returned when payload is not a valid JSON content.\n",
"value": {
"status": "400,",
"error": "JSON error: Error occurred while parsing request parameters"
}
},
"RecordNotFound": {
"description": "Returned when record with specified ID does not exist or current user does not have permissions to access it.\n",
"value": {
"message": "record not found"
}
},
"InvalidProductURLFormat": {
"description": "Returned when `product_url` does not have a valid URL format.\nFor example when it doesn't have protocol (`https://`) specified.\n",
"value": {
"product_url": [
"invalid format"
]
}
},
"InvalidHubTypePH": {
"description": "Returned when performing on Connected Hub a request valid only for Primary or Standalone Hub.\n",
"value": {
"message": [
"hub must be primary"
]
}
},
"hub_responses_InvalidSubdomain": {
"description": "Returned when `subdomain` is invalid or not available.\n",
"value": {
"subdomain": [
"already taken",
"not allowed"
]
}
},
"QuotaReached": {
"description": "Returned when the Connected Hubs quota for current Primary\nHub has been reached or Connected Hubs are not available\nfor current Primary Hub plan.\n",
"value": {
"connected_hub": [
"limit reached"
]
}
},
"OK": {
"description": "Operation was successful.",
"value": {
"message": "OK"
}
},
"InvalidDeletedParam": {
"description": "Returned when deleted param is invalid.\n",
"value": {
"deleted": [
"must be one of: true, false, all"
]
}
},
"InvalidExtendParam": {
"description": "Returned when `extend` contains property that does not exist or not support extending.\n",
"value": {
"extend[0]": [
"must be one of: flags"
]
}
},
"CreateBasicExample": {
"description": "Basic example of creating incident affecting two services.\n",
"value": {
"title": "Example incident title",
"start_time": "2025-05-02 12:34:56",
"incident_type": "investigating",
"body": "Incident body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
]
}
},
"CreateSilentDraft": {
"description": "Example of creating silent incident draft.
Please note that `silent` affects notification to subscribers and does not affect nor suppress draft notifications to team members.\n",
"value": {
"title": "Example incident title - silent + draft",
"start_time": "2025-05-02 12:34:56",
"incident_type": "investigating",
"body": "Incident body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
],
"silent": true,
"state": "draft"
}
},
"MissingRequiredValues": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"title": [
"is missing"
],
"start_time": [
"is missing"
],
"incident_type": [
"is missing"
]
}
},
"StartTimeInFuture": {
"description": "Returned when `start_time` is set in future. Incidents unlike Maintenance events, can't be created in future.\n",
"value": {
"start_time": [
"cannot_be_in_future"
]
}
},
"WrongServiceIDs": {
"description": "Returned when `service_id` doesn't match any service in currently used Hub. Same error is returned when there is no service with such ID as well as when service with such ID exists but in different Hub.\n",
"value": {
"service_statuses": [
"wrong_hub"
]
}
},
"Requests-CreateBasicExample": {
"description": "Basic example of creating incident update affecting two services.\n",
"value": {
"title": "Example incident title",
"start_time": "2025-05-02 12:34:56",
"incident_type": "investigating",
"body": "Incident body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
]
}
},
"CreateResolving": {
"description": "Resolving incident by creating incident update with `\"incident_type\": \"resolved\"`.\n",
"value": {
"title": "Example incident title",
"start_time": "2025-05-02 12:34:56",
"incident_type": "resolved",
"body": "Final message
with basic HTML tags."
}
},
"UpdateAlterBody": {
"description": "Change incident update message.\n",
"value": {
"body": "New incident update message."
}
},
"UpdatePublishDraft": {
"description": "Publish incident update which was created as draft.\n",
"value": {
"state": "published"
}
},
"templates_responses_MissingRequiredValues": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"template": [
"must_have_title_or_body"
]
}
},
"InvalidServiceIDs": {
"description": "Returned when some of service IDs are invalid or does not belong to current Hub.\n",
"value": {
"service_statuses": [
"not all services belong to the hub"
]
}
},
"maintenances_Requests-CreateBasicExample": {
"description": "Basic example of creating maintenance affecting two services.\n",
"value": {
"title": "Example maintenance title",
"start_time": "2025-05-02 12:34:56",
"end_time": "2025-05-02 13:34:56",
"body": "Maintenance body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
]
}
},
"CreateMonthlyRecurring": {
"description": "Example of creating recurring maintenance that should repeat every month.\n",
"value": {
"title": "Example maintenance title",
"start_time": "2025-05-02 12:34:56",
"end_time": "2025-05-02 13:34:56",
"body": "Maintenance body
with basic HTML tags.",
"service_statuses": [
{
"service_id": 17363,
"status": "degraded-performance"
},
{
"service_id": 17155,
"status": "down"
}
],
"event_repeat": {
"interval": "month"
}
}
},
"maintenance_responses_MissingRequiredValues": {
"description": "Returned when payload is missing values for mandatory fields.\n",
"value": {
"title": [
"is missing"
],
"start_time": [
"is missing"
],
"end_time": [
"is missing"
]
}
},
"AlreadySubscribed": {
"description": "Returned when address is already subscribed to current Hub.
`subscriptions[0]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions[0].address": [
"already subscribed",
"already taken"
]
}
},
"DuplicatedMethod": {
"description": "Returned when there is more than one subscription for any method name.
`subscriptions[0]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions": [
"can not have multiple identical methods"
]
}
},
"InvalidAddress": {
"description": "Returned when address of subscription is invalid for given method name.
`subscriptions[2]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions[2].address": [
"invalid"
]
}
},
"subscriber_responses_InvalidServiceIDs": {
"description": "Returned when address of subscription is invalid for given method name.
`subscriptions[1]` refers to first subscription passed in `subscriptions` value of request body.\n",
"value": {
"subscriptions[1].services_selection": [
"invalid"
]
}
},
"DuplicatedIDPID": {
"description": "Returned when `idp_id` has already been used in current Hub.\n",
"value": {
"idp_id": [
"already taken"
]
}
},
"InvalidSubscriber": {
"description": "Returned when SubscriberID is invalid.
\n",
"value": {
"message": "subscriber not found"
}
},
"CreateMinimalEmail": {
"description": "Minimal example creating email subscription.\n",
"value": {
"address": "example@statushub.com",
"method_name": "email",
"services_selection": {
"all": true
}
}
},
"CreateBasicEmail": {
"description": "Example creating email subscription with less verbose option and services selection.\n",
"value": {
"address": "example@statushub.com",
"method_name": "email",
"services_selection": {
"service_ids": [
17155,
17363
]
},
"less_verbose": true
}
},
"DuplicatedAddress": {
"description": "Returned when there is more than one subscription for any method name for current Hub.\n",
"value": {
"address": [
"already taken",
"already subscribed"
]
}
},
"subscription_responses_DuplicatedMethod": {
"description": "Returned when there is more than one subscription for any method name for current Subscriber.\n",
"value": {
"method_name": [
"already subscribed"
]
}
},
"subscription_responses_InvalidAddress": {
"description": "Returned when address of subscription is invalid for given method name.\n",
"value": {
"address": [
"invalid"
]
}
},
"InvalidSubscriberID": {
"description": "Returned when SubscriberID is invalid.
Returned also when trying to create Subscription for deleted Subscriber.\n",
"value": {
"subscriber_id": [
"invalid"
]
}
},
"MissingServicesSelection": {
"description": "Returned when `services_selection` parameter is missing or incomplete.
Example of incomplete `services_selection` is `{\"services_selection\": {\"all\": false}}` which would indicate that a subset of services should be used but the services list was not provided.\n",
"value": {
"services_selection": [
"is missing"
]
}
},
"ForbiddenRestore": {
"description": "Returned when restoring subscription is not allowed because such subscription would violate validations.
For example when attempting to restore subscription with address that is already being used by an active (not deleted) subscription in the same Hub.\n",
"value": {
"message": "not authorized"
}
},
"InvalidArchivedParam": {
"description": "Returned when archived param is invalid.\n",
"value": {
"archived": [
"must be one of: true, false, all"
]
}
},
"AttemptToModifyArchivedGroup": {
"description": "Returned when trying to modify group that was archived.\n",
"value": {
"message": "not authorized"
}
},
"AttemptToModifyArchivedService": {
"description": "Returned when trying to modify service that was archived.\n",
"value": {
"message": "not authorized"
}
},
"InvalidHubTypeCH": {
"description": "Returned when performing on Primary or Standalone Hub a request valid only for Connected Hub.\n",
"value": {
"message": [
"hub must be connected"
]
}
},
"InvalidEndDateParam": {
"description": "Returned when date param can't be parsed as valid date.
For example: `end_date=2025-02-31`\n",
"value": {
"end_date": [
"must be a date"
]
}
},
"TooFarEndDateParam": {
"description": "Returned when `end_date` param is too far apart from `start_date`.
Response specifies maximum value of `end_date` that can be used with provided `start_date`.\n",
"value": {
"end_date": [
"must be less than or equal to 2024-08-01"
]
}
}
}
},
"x-tagGroups": [
{
"name": "Events",
"tags": [
"Incident",
"Incident Update",
"Maintenance",
"Incident Update Template",
"Maintenance Template",
"Platform Alert"
]
},
{
"name": "Hub",
"tags": [
"Hub",
"Hub Privacy",
"Assets",
"Group",
"Service",
"Service Integration",
"Connected Group",
"Connected Service",
"External Application",
"Uptime"
]
},
{
"name": "Visitors",
"tags": [
"Subscription",
"Subscriber",
"Subscriber Subscription"
]
}
]
}