canonical: https://jentic.com/apis/rootly.com/rootly

# Rootly API v1

The Rootly API runs incident response and on-call for engineering teams through the JSON:API format. It declares, triages, mitigates, resolves, and cancels incidents, assigns incident roles to users, posts timeline events, and tracks action items and retrospectives. Alerts can be created from sources such as Datadog, PagerDuty, Sentry, and Grafana, then acknowledged, resolved, grouped, or attached to an incident. On-call schedules, rotations, override shifts, escalation policies, heartbeats, status pages, and workflows are managed through the same API.

## For AI agents

Declare and resolve Rootly incidents, raise and acknowledge alerts, read on-call schedules and shifts, post timeline events, and track incident action items.

## Scope

Does not collect metrics or logs, host application monitoring, or send chat messages itself. Use for managing incidents, alerts, on-call schedules, and follow-ups in Rootly only.

## Capabilities

- Declare an incident with title, severity_id, service_ids, and labels, then move it to mitigated or resolved with a message
- Create alerts with a source such as datadog or sentry and acknowledge or resolve them
- Attach existing alerts to an incident and list the alerts on it
- Read on-call shifts for a schedule and create override shifts
- Add timeline events to an incident with internal or external visibility
- Create incident action items with priority, assignee, and due_date
- Ping a heartbeat so Rootly knows a scheduled job is still running

## Use cases

### AI incident co-pilot

An on-call engineer wants an agent that handles incident bookkeeping while they debug. Through Jentic the agent searches for 'declare an incident', loads Rootly's createIncident, and opens the incident with a title, severity_id, and service_ids, with the bearer token injected by the developer's own instance. As the response progresses it posts timeline updates with createIncidentEvent and, once the fix lands, calls resolveIncident with a resolution_message.

Example prompt: Call POST `/v1/incidents` with title 'Checkout latency spike', severity_id for SEV1, and service_ids for checkout, then call POST `/v1/incidents/{incident_id}/events` with event 'Rolled back deploy 4821' and visibility 'internal'

### Alert triage from monitoring sources

Alerts from tools such as Datadog, Sentry, Grafana, or CloudWatch land in Rootly with a source, summary, and urgency. POST `/v1/alerts/{id}/acknowledge` and POST `/v1/alerts/{id}/resolve` close the loop on each one, and POST `/v1/incidents/{incident_id}/alerts` attaches related alerts to an incident so responders see the full picture in one place.

Example prompt: Call GET `/v1/alerts`, acknowledge open alerts from source 'datadog' with POST `/v1/alerts/{id}/acknowledge`, and attach them to the active incident with POST `/v1/incidents/{incident_id}/alerts`

### On-call lookup and coverage swaps

Knowing who is on call, and covering when they are not available, is a daily task. GET `/v1/schedules/{id}/shifts` returns the shifts on a schedule, and POST `/v1/schedules/{schedule_id}/override_shifts` records an override when someone swaps a shift, while escalation policies define who is paged next.

Example prompt: Call GET `/v1/schedules/{id}/shifts` for the payments schedule for today and return the user on shift

### Retrospective follow-through

Incidents only improve reliability if their follow-ups get done. POST `/v1/incidents/{incident_id}/action_items` creates an action item with a summary, kind of task or follow_up, priority, assignee, and due_date, and GET `/v1/action_items` lists every action item across the organization so overdue work can be chased.

Example prompt: Call POST `/v1/incidents/{incident_id}/action_items` with summary 'Add alerting on queue depth', kind 'follow_up', priority 'high', and due_date '2026-12-01'

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/incidents` | Declare an incident |
| GET | `/v1/incidents` | List and filter incidents |
| PUT | `/v1/incidents/{id}/resolve` | Resolve an incident |
| POST | `/v1/incidents/{incident_id}/events` | Add a timeline event |
| POST | `/v1/alerts` | Create an alert |
| POST | `/v1/alerts/{id}/acknowledge` | Acknowledge an alert |
| GET | `/v1/schedules/{id}/shifts` | Get schedule shifts |
| POST | `/v1/incidents/{incident_id}/action_items` | Create an incident action item |

## Key resources

- **Incidents** — Incidents with severity, services, environments, roles, subscribers, events, and lifecycle actions
- **Alerts** — Alerts from monitoring sources with urgency, grouping, acknowledgement, and resolution
- **Schedules** — On-call schedules, rotations, shifts, override shifts, and shadows
- **Escalation policies** — Escalation levels and paths that decide who is paged
- **Action items** — Tasks and follow-ups attached to incidents
- **Status pages** — Public status pages, templates, and incident status page events

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 52 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 47 / 100
  - Developer Experience & Jentic Compatibility: 63 / 100
  - AI-Readiness & Agent Experience: 50 / 100
  - Agent Usability: 43 / 100
  - Security: 60 / 100
  - AI Discoverability: 65 / 100
- **View full report:** https://jentic.com/apis/rootly.com/rootly/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Rootly by hand means generating an API key, sending it as a bearer with the JSON:API media type, wrapping every write in a JSON:API data and attributes envelope, and paging with page[number] and page[size]. Through Jentic you install once, import Rootly from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Rootly puts the incident id in the URL path (`/v1/incidents/{id}/resolve`, `/v1/incidents/{incident_id}/events`), so a rule can pin your agent to one incident and the operations you pick. You choose the operations it may call, so destructive ones like DELETE `/v1/incidents/{id}` or deleteSchedule are not included unless you add them.
- **Credential handling:** Your Rootly API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'declare an incident' or 'who is on call', and Jentic returns the matching Rootly operation, such as createIncident or getScheduleShifts, with its input schema.

## Related APIs

- **PagerDuty** — Incident alerting, on-call scheduling, and escalation
- **Opsgenie** — Alert routing and on-call management
- **Slack** — Team chat where incident channels and updates live

## FAQ

### What authentication does the Rootly API use?

The Rootly OpenAPI spec declares bearer_auth, an HTTP bearer token sent as Authorization: Bearer with your API key. The spec's description says keys are generated under Account, Manage API keys, and requests use the JSON:API media type. Through Jentic the key is stored by your own instance and added as the bearer at call time.

### Can I move a Rootly incident through its lifecycle with the API?

Yes. Dedicated operations change state: PUT `/v1/incidents/{id}/in_triage`, PUT `/v1/incidents/{id}/mitigate` with a mitigation_message, PUT `/v1/incidents/{id}/resolve` with a resolution_message, PUT `/v1/incidents/{id}/cancel`, and PUT `/v1/incidents/{id}/restart.` PUT `/v1/incidents/{id}/duplicate` marks an incident as a duplicate.

### What are the rate limits for the Rootly API?

The Rootly OpenAPI spec states a limit of approximately 1500 GET calls every 60 seconds per API key, and a stricter limit on PUT, POST, PATCH, and DELETE calls, with a 429 response when exceeded. Responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.

### Is there a Rootly MCP server?

You do not need an MCP server to give your agent Rootly. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent finds the incident, alert, and schedule operations it needs by intent rather than loading hundreds of tool definitions into its context.

### How do I declare an incident through Jentic?

Search Jentic for 'declare an incident in Rootly', load createIncident (POST `/v1/incidents`), and send a JSON:API body whose attributes include title and optionally severity_id, service_ids, and labels. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the Rootly API?

Yes. For an incident scribe, write a rule that allows GET `/v1/incidents/{id}` and POST `/v1/incidents/{incident_id}/events`, scoped to the incident id you hand it. The agent can read that incident and add timeline notes, but cannot resolve or delete it, change schedules, or touch escalation policies, and every call it makes is logged.
