# Rootly

> Incident response, service context and follow-up progress beside the component they explain.

Connect a Rootly service to the stratum for a system component, or link an
incident to the stratum explaining a failure or recovery process. Readers can
understand the response in the diagram's context and open Rootly for the full
incident record. Blueprintr reads information; incident management stays in
Rootly.

## Connect and choose an object

1. You need an Enterprise licence, edit access to the blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In Rootly, open **Organization Settings → API Keys → Generate New API Key**.
   Prefer a dedicated **Global API key** assigned read-only Incident Response
   and, only if needed, On-Call roles. Personal keys inherit their creator's
   access; Team keys inherit Team Admin permissions. See
   [Rootly's API-key guide](https://docs.rootly.com/api-reference/overview).
3. In Blueprintr, open **Settings → Continuum** on the organisation or team, go
   to **Operational integrations**, and choose **New integration**. Select
   **Rootly** as the **Type**, give the connection a **Name**, enter the **API
   key**, review the audience and optional settings, then choose **Connect &
   verify**. Verification checks service and
   incident reads. There is no separate enable step.
4. Save the blueprint, open the relevant stratum, and choose **Continuum Link**.
   Search for the service or incident and review its identity before linking.
   **Suggest integrations…** on a shape and **Scan for integrations** across the
   blueprint both propose Rootly matches, and attach nothing until you apply
   them.

Blueprintr uses Rootly's hosted API at `api.rootly.com`. This connection does not
provide an alternative regional or self-hosted endpoint.

## Choose the information and audience

| Setting | Default | What it changes |
| --- | --- | --- |
| Rootly content audience | Blueprint editors | Keeps saved Rootly details visible to blueprint editors. Choose the reader-visible option, **All Blueprint readers**, only after approving the information for everyone who can read the blueprint. Its full label adds "approved metadata". |
| Service ownership and context | On | For linked services, adds related services, teams, environments, repository names and deployment names. Turn it off to omit optional context reads. |
| On-call coverage | Off | For linked services, adds [on-call coverage](https://docs.rootly.com/api-reference/oncalls/list-on-calls) when the key and Rootly account support it. Individual responders and their contact details are omitted. |
| Incident action item counts | On | For linked incidents, adds aggregate task and follow-up progress from [incident action items](https://docs.rootly.com/api-reference/incidentactionitems/list-incident-action-items). Task descriptions and assignees are omitted. |

The baseline key needs read access to **services and incidents**. Context may
also require team and environment reads; follow-up summaries need incident
action-item reads. On-call coverage needs access to Rootly's on-call data and
the relevant product entitlement. These are permissions on the key's assigned
roles, not OAuth scope strings. Disable an optional capability instead of
granting unrelated administrative access.

Rootly incidents marked private, or without a reliable privacy designation,
are excluded from selection and saved incident data under either audience
setting. Rootly's non-private designation does not itself make an incident
appropriate for the public. Review titles, service names and relationships
before switching to the reader-visible audience.

> [!NOTE]
> Under the editor audience, a candidate is offered under a generic title such as
> "Rootly service" or "Rootly incident INC-42" rather than its real name, because
> a candidate title can become a stratum filename and a filename sits outside the
> audience gate. A stratum minted from one of these is named accordingly.

## Read the snapshot

A service panel separates active response from recent history and maintenance.
Normal incidents and sub-incidents are distinguished by kind; test incidents
do not count as production incidents. The active view is independent of the
30-day history window, so an older unresolved incident can still be relevant.
Maintenance has its own state and planned window when available; it does not
become an outage merely because it is in progress. Rootly documents these filters in its
[incident API](https://docs.rootly.com/api-reference/incidents/list-incidents).

An incident panel shows response state, severity, related services and lifecycle
times when available. **Mitigated** means impact has been reduced or halted;
it does not mean response work is complete. Follow-up progress helps distinguish
incident resolution from outstanding improvement work. Open Rootly to read
descriptions, communicate with responders or change the record.

Opening a tab displays saved data. Re-fetch with the circular-arrows icon on
the linked row, whose tooltip reads "Re-fetch this integration's data". Rootly
snapshots indicate that another refresh is needed after five minutes; this is
a freshness warning, not automatic polling. On-call coverage is limited to the
time checked. Incident counts describe retrieved records, not a guarantee that
the system is healthy.

## Missing information and recovery

An unavailable incident list, incomplete pagination or unreadable optional
section is shown as unavailable or partial, rather than as zero incidents or
no outstanding work. If a whole refresh fails, the prior snapshot remains with
a warning. Check the key's role and expiry; for rate limits, wait for the stated
retry interval before refreshing again.

Rotate a credential with **Rotate token**, then **Verify & replace**, which
swaps it only if the new key verifies. **Suspend** stops search and refresh while
leaving saved snapshots readable, and **Resume** restarts it. The broken-link
icon on the linked row removes the binding. The connection can be deleted after
its bindings have been removed.

## Copies and rollout checks

New snapshots restricted to editors use Blueprintr's existing audience controls for
readers, embeds, viewer exports and search/AI indexing. Editor exports and
backups retain the source. Approved reader-visible snapshots follow the
blueprint's audience, including anonymous readers of a public blueprint.

Settings apply to subsequent fetches. Changing the audience does not rename
existing Strata or link labels, or remove authored notes outside the managed
panel. Review those separately before relying on a narrower audience. Templates,
version history, exports and other existing copies are not retroactively
rewritten or recalled by an audience change, key revocation or unlink.

Before operational rollout, verify the connection against your Rootly account:
service membership, a known older active incident, maintenance, private-incident
exclusion, optional permissions and on-call coverage. Local fixture tests do
not establish your account's entitlements or replace this live check.