Skip to content

Incident

Incident is a most important event type.
Incident represents an event that:

  • Started in the past,
  • Have updates which can be added while incident is being handled,
  • During creation and during its duration the total duration or end of the incident is not known,
  • Is resolved when resolved Incident Update is created for this incident,
  • Have non-0 duration. This means that Incident can't be created with resolved incident type.

Most typical use case:

  • Hub Page list various customer-facing services,
  • When one of the services has an outage, Incident is created manually or through automation,
  • While team is working on restoring the service Incident Update entries are added manually or through automation to this incident to let customers know what's happening,
  • Once issue is resolved, Incident Update with monitoring incident type is being created while team is keeping an eye on service health,
  • Once situation is stable, Incident Update with resolved incident type is being created which ends the Incident.
Operations

Create an Incident

Request

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

Security
ApiKeyAuth
Path
subdomainstringrequired

Unique subdomain of requested Hub.

Query
api_versionstring

Api version

Value:"V3-R1"
Bodyapplication/json
titlestringrequired

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

Example:"Title of the event"
start_timestring or null, (date-time)required

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

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

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

Enum:"investigating""identified""monitoring""resolved"
Example:"investigating"
service_statusesArray of objectsrequired

Describes affected services and their statuses.

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

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

Default:false
statestring or null

State of Incident or Incident Update:

  • draft - Not published on Hub Page,
  • unconfirmed - Published on Hub Page but marked as unconfirmed,
  • published - Published on Hub Page.
Default:"published"
Enum:"draft""unconfirmed""published"
Example:"published"
original_incident_idinteger, >= 1

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

Example:102

Basic example of creating incident affecting two services.

curl -i -X POST \
  'https://subdomain-of-your-account.app.statushub.io/api/v3/hubs/{subdomain}/incidents?api_version=V3-R1' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY_HERE' \
  -d '{
    "title": "Example incident title",
    "start_time": "2025-05-02 12:34:56",
    "incident_type": "investigating",
    "body": "Incident body<br>with basic HTML tags.",
    "service_statuses": [
      {
        "service_id": 17363,
        "status": "degraded-performance"
      },
      {
        "service_id": 17155,
        "status": "down"
      }
    ]
  }'

Responses

OK

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

Author email

titlestring

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

created_atstring, (date-time)

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

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

Timestamp of the start_time of the first (by start_time) Incident Update.
ISO8601 formatted time (UTC).

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

Timestamp of last modification of record.
ISO8601 formatted time (UTC).

Example:"2020-09-01T08:29:00Z"
end_timestring or null, (date-time)

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

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