Explore documentation
  1. Welcome to Incidents 👋
  2. Frequently Asked Questions
  3. On-call scheduling and alerting
    1. Get started
    2. Slack and other integrations ↗
    3. Tag on-call in Slack
    4. Mobile apps ↗
    5. Connecting external calendars
    6. Advanced guide
  4. Incident management
    1. Get started
    2. AI SRE investigations
    3. Post mortems
    4. Metadata & Catalog
    5. Screening alerts
    6. Reporting ↗
  5. Monitoring
    1. Get started
    2. Working with monitors
    3. Customizing monitors
    4. Monitor types
  6. Status pages
    1. Get started
    2. Advanced guide
  7. Incidents API
    1. Getting an API token
    2. Pagination
    3. Monitors
    4. Heartbeats
    5. On-call & incidents
      1. On-call schedule
      2. On-call schedule events
      3. On-call schedule rotations
      4. Escalation policies
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
        1. List incidents GET
        2. Get incident GET
        3. List incident timeline GET
        4. Create incident POST
        5. Acknowledge incident POST
        6. Resolve incident POST
        7. Reopen incident POST
        8. Escalate incident POST
        9. Remove incident DELETE
      9. Comments
    6. Status pages
    7. Metadata
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

Create incident

This will create a new incident and alert the current on-call person.

POST https://incidents.betterstack.com/api/v3/incidents

Headers

Authorization
required string

Bearer $TOKEN

Content-Type
string

application/json

Body parameters

team_name
string

Required if using global API token to specify the team which should own the resource

requester_email
required string

E-mail of the user who requested the incident. Not required when authenticating with an OAuth token

name
string

Short name of the incident

summary
required string

Brief summary of the incident

description
string

Full description of the incident

call
boolean

Should we call the on-call person? Defaults to false.

sms
boolean

Should we send an SMS to the on-call person? Defaults to false.

email
boolean

Should we send an e-mail to the on-call person? Defaults to false.

push
boolean

Should we send a push notification to the on-call person? Defaults to false.

critical_alert
boolean

Should we send a critical push notification that ignores the mute switch and Do Not Disturb mode? Defaults to false.

team_wait
integer

How long to wait before escalating the incident to the team. Leave blank to disable escalating to the entire team. In seconds.

policy_id
string

The ID of the escalation policy with which you'd like to escalate this incident

metadata
object

An object with metadata keys as the object keys and either a single metadata value or an array of metadata values as the object values. Each value is a plain string or an object with a type and the fields that identify the item, as described for values when creating a metadata record. All values under one key must be of the same type and must not repeat.

201

The incident was successfully created

Response body

{
  "data": {
    "id": "123456789",
    "type": "incident",
    "attributes": {
      "name": "uptime homepage",
      "url": "https://uptime.betterstack.com/",
      "http_method": "get",
      "cause": "Status 500",
      "incident_group_id": null,
      "started_at": "2020-03-09T17:37:56.662Z",
      "acknowledged_at": null,
      "acknowledged_by": null,
      "resolved_at": null,
      "resolved_by": null,
      "team_name": "Testing team",
      "response_content": "\n404 Not Found\n\nNot Found\nThe requested URL /fail was not found on this server.\n",
      "response_options": "{}",
      "regions": [
        "us",
        "eu",
        "as",
        "au"
      ],
      "response_url": null,
      "screenshot_url": null,
      "origin_url": null,
      "escalation_policy_id": null,
      "call": true,
      "sms": true,
      "email": true,
      "push": true
    },
    "relationships": {
      "monitor": {
        "data": {
          "id": "2",
          "type": "monitor"
        }
      }
    }
  }
}
404

Authentication failed

Example cURL

Example Example with metadata 
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "summary": "Test incident",
    "requester_email": "my-great-email@example.com",
    "description": "No need to worry, everything is fine, this is just testing the great Incidents API."
  }'
curl --request POST \
  --url https://incidents.betterstack.com/api/v3/incidents \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "summary": "Test incident",
    "requester_email": "my-great-email@example.com",
    "description": "No need to worry, everything is fine, this is just testing the great Incidents API.",
    "metadata": {
      "Affected Services": [
        {
          "value": "Homepage"
        },
        {
          "value": "Login"
        }
      ],
      "On-call Calendar": [
        {
          "type": "Schedule",
          "name": "Primary calendar"
        }
      ]
    }
  }'


Previous article

List incident timeline

Next article

Acknowledge incident