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
        1. List on-call schedule events GET
        2. Get on-call schedule event GET
        3. Create on-call schedule event POST
        4. Update on-call schedule event PATCH
        5. Remove on-call schedule event DELETE
        6. Bulk update on-call schedule events PUT
      3. On-call schedule rotations
      4. Escalation policies
      5. Escalation policy groups
      6. Severities
      7. Severity groups
      8. Incidents
      9. Comments
    6. Status pages
    7. Metadata
    8. Integrations
    9. Team members
    10. Organization roles
    11. Usage
    12. Reporting

Create an on-call schedule event

Create a new event in the given on-call schedule.

POST https://incidents.betterstack.com/api/v2/on-calls/{schedule_id}/events

URL parameters

schedule_id
required string

The ID of the on-call schedule you want to create the event for. Use default to refer to the default on-call schedule for the team.

Headers

Authorization
required string

Bearer $TOKEN

Body parameters

starts_at
required date

Start time of the event. Must be today at 0:00 UTC or later.

ends_at
required date

End time of the event.

users
required array

List of e-mail addresses of users that will be on-call during this event. Each user must be a member of the schedule's team with a role that can respond to incidents, such as Responder.

override
boolean

Whether this event is an override. Override events take precedence over regular scheduled events. Defaults to false.

200

Event was created.

Response body

{
  "id": 12345678,
  "starts_at": "2025-01-01T09:00:00Z",
  "ends_at": "2025-01-01T17:00:00",
  "users": [
    "tomas@betterstack.com"
  ],
  "override": false
}

Example cURL

Regular on-call event Override event 
curl --request POST \
  --url "https://incidents.betterstack.com/api/v2/on-calls/default/events" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "starts_at": "2025-01-01T09:00:00Z",
    "ends_at": "2025-01-01T17:00:00",
    "users": ["tomas@betterstack.com"]
  }'
curl --request POST \
  --url "https://incidents.betterstack.com/api/v2/on-calls/default/events" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "starts_at": "2025-01-01T09:00:00Z",
    "ends_at": "2025-01-01T17:00:00",
    "users": ["tomas@betterstack.com"],
    "override": true
  }'


Previous article

Get a single on-call schedule event

Next article

Update on-call schedule event