Rootly

Rootly

This connector works with Rootly incident management through its REST API (https://api.rootly.com, JSON:API): incidents with their timeline, action items and status page updates, alerts, the service catalog (services, functionalities, teams, environments, severities, incident types), users, on-call (who is on call, schedules, shifts, escalation policies), status pages and retrospectives. It can declare, update, mitigate and resolve incidents, add timeline notes and action items, acknowledge and resolve alerts and publish status page updates.

Setup (2 minutes)

1. In Rootly open the organization menu, Organization Settings, API Keys and create a key. A Global key sees the whole organization; a Team key only that team's records; a Personal key acts with your own permissions.
2. Give the key a role that can read what you need, plus write permission for incidents, alerts and action items if the agent should change them.
3. Paste the key into ROOTLY_API_KEY and run rootly_get_current_user to check it.

Workflow

• What is going on: rootly_list_incidents with status: "started,mitigated" (or in_triage), then rootly_get_incident, rootly_list_incident_events for the timeline and rootly_list_incident_action_items. Look up ids with rootly_list_severities, rootly_list_services, rootly_get_service, rootly_list_functionalities, rootly_get_functionality, rootly_list_teams, rootly_get_team, rootly_list_environments, rootly_list_incident_types and rootly_list_users.
• Run an incident: rootly_create_incident (pass an idempotency_key; use kind test for a try), rootly_update_incident for title, summary, severity, services or status, rootly_add_incident_event for timeline notes, then rootly_mitigate_incident and rootly_resolve_incident.
• Tasks and follow-ups: rootly_list_action_items across incidents, rootly_get_action_item, rootly_create_action_item, rootly_update_action_item (e.g. status done).
• Alerts: rootly_list_alerts (status triggered or open), rootly_get_alert for the raw payload, rootly_acknowledge_alert, rootly_resolve_alert.
• On-call: rootly_list_oncalls answers who is on call now (or in a window); rootly_list_schedules, rootly_get_schedule, rootly_get_schedule_shifts, rootly_list_shifts and rootly_list_escalation_policies for the details.
• Communicate: rootly_list_status_pages, rootly_get_status_page, rootly_list_incident_status_page_events, then rootly_create_status_page_event to publish an update.
• Learn: rootly_list_retrospectives and rootly_get_retrospective.

Before writing: a normal incident runs workflows, opens a Slack channel and can page people; a status page update is public and can e-mail subscribers. Confirm with the user first. A private incident cannot be made public again.

Reading the answers: JSON:API: records are in data (id, type, attributes, relationships), embedded records from include in included. Ids are UUIDs, except user ids (numbers). The human incident number is attributes.sequential_id (INC-123). Times are ISO 8601, in UTC unless a time zone is given. rootly_list_incidents and rootly_list_alerts return a compact set of attributes by default (fields); pass fields: "" for all of them. Zoom meeting passwords and host links are left out of incident answers.

Paging: lists return meta with current_page, next_page (null on the last page), total_count and total_pages; call again with page_number. Incidents and alerts also accept the cursor page_after from meta.next_cursor. Keep page_size small, Rootly records are large.

Errors: 401 means a wrong or revoked key, 403 a key whose role or team does not allow the call, 404 an unknown id or one outside the key's team, 422 a validation error whose errors name the field, 429 the rate limit (the X-RateLimit-* headers tell when it resets; wait and retry).