API Recipes - Rootly

Four requests that cover most first integrations. Replace the API key and the IDs with your own before you run them. Every request needs the same two headers, so they are not repeated in the explanations:

Content-Type: application/vnd.api+json
Authorization: Bearer YOUR-API-KEY

Use a Global API key (organization in the API) rather than a personal one for anything long-lived. A personal key has its creator’s permissions and is deleted when they leave the organization. A Team API key cannot declare incidents or create webhook endpoints. The key’s role must allow each action you call. See API Keys.

Declare an Incident

curl --request POST \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/incidents \
--data '{
  "data": {
    "type": "incidents",
    "attributes": {
      "title": "Checkout latency above threshold",
      "summary": "p99 on the checkout endpoint has been above 2s for 10 minutes.",
      "severity_id": "SEVERITY_ID",
      "service_ids": ["SERVICE_ID"],
      "environment_ids": ["ENVIRONMENT_ID"],
      "kind": "test"
    }
  }
}'

title is optional, and Rootly generates one if you omit it. That is convenient for a quick call and a poor idea for an integration: the title is the first thing everyone reads in the incident list. The example sends kind: "test" on purpose. Run it as written and you get a test incident, not a production one. Test incidents are left out of the default dashboards. Workflows still run when their incident kind condition includes Test, and the default workflow that creates an incident Slack channel includes it. Remove that line when you go live, or your real integration will only ever declare test incidents. Useful attributes beyond the basics: private for a sensitive incident, parent_incident_id to declare a sub-incident, and alert_ids to attach the alerts that prompted it.

Page Someone

Paging happens by creating an alert with a notification target. The alert is the record; the target is who gets woken.

curl --request POST \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/alerts \
--data '{
  "data": {
    "type": "alerts",
    "attributes": {
      "summary": "Payments queue depth critical",
      "notification_target_type": "EscalationPolicy",
      "notification_target_id": "ESCALATION_POLICY_ID"
    }
  }
}'

notification_target_type can be User, Group, EscalationPolicy, Service, or Functionality. Prefer an EscalationPolicy or a Service over a named User. A user ID in a script is a person who will eventually leave, be on holiday, or move teams, and the script will keep paging them regardless. An escalation policy is the same call with a rota behind it.

Notification targets require Rootly On-Call.

To page several destinations in one request, use notification_targets with any combination of the types above.

Post an Alert Without Paging

The same endpoint records an alert without paging anyone if you omit the notification target.

curl --request POST \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/alerts \
--data '{
  "data": {
    "type": "alerts",
    "attributes": {
      "summary": "Nightly reconciliation job found 3 mismatches",
      "description": "Details in the job log.",
      "service_ids": ["SERVICE_ID"]
    }
  }
}'

summary is the only required attribute.

Wire a Webhook

curl --request POST \
--header 'Content-Type: application/vnd.api+json' \
--header 'Authorization: Bearer YOUR-API-KEY' \
--url https://api.rootly.com/v1/webhooks/endpoints \
--data '{
  "data": {
    "type": "webhooks_endpoints",
    "attributes": {
      "name": "Ops relay",
      "url": "https://ops.example.com/hooks/rootly",
      "secret": "YOUR-SIGNING-SECRET",
      "enabled": true,
      "event_types": ["incident.created", "incident.resolved"]
    }
  }
}'

name and url are required, and name must be unique in your organization. Subscribe only to the events you handle: a receiver that ignores most of what it gets has logs that are hard to use when something breaks. Event types are on Webhooks. Set secret and verify the signature. Every delivery carries X-Rootly-Signature; an endpoint that does not check it will accept anything anyone sends to that URL. See Verifying Webhook Signatures. custom_headers takes up to 10 name/value pairs if your receiver needs its own auth header.

Finding the IDs

Every recipe above takes IDs rather than names. List the collection and read the id:

You need	Call
`severity_id`	`GET /v1/severities`
`service_ids`	`GET /v1/services`
`environment_ids`	`GET /v1/environments`
`group_ids` (teams)	`GET /v1/teams`
`ESCALATION_POLICY_ID`	`GET /v1/escalation_policies`

IDs are stable, so look them up once and keep them in configuration rather than resolving names on every call.

API Overview

Authentication, pagination, rate limits, and key management.

Webhooks

Event types, delivery contract, and signature verification.

SDKs

Client libraries, if you would rather not hand-roll requests.

Declare an Incident

Page Someone

Post an Alert Without Paging

Wire a Webhook

Finding the IDs

Related Pages

API Overview

Webhooks

SDKs