> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rootly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Recipes

> Four copy-paste recipes for the first things teams automate with the Rootly API: declare an incident, page someone, post an alert, and wire a webhook.

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
```

> [!TIP]
>
> 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](https://docs.rootly.com/api-reference/overview.md).

***

## Declare an Incident

```bash theme={null}
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.

```bash theme={null}
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.

> [!NOTE]
>
> 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.

```bash theme={null}
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

```bash theme={null}
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](https://docs.rootly.com/configuration/webhooks.md).

**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](https://docs.rootly.com/configuration/webhooks.md#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.

***

## Related Pages

> [card] [API Overview](https://docs.rootly.com/api-reference/overview.md)
>
> Authentication, pagination, rate limits, and key management.

> [card] [Webhooks](https://docs.rootly.com/configuration/webhooks.md)
>
> Event types, delivery contract, and signature verification.

> [card] [SDKs](https://docs.rootly.com/api-reference/sdks.md)
>
> Client libraries, if you would rather not hand-roll requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.