# incident.io

> Catalog service context and the incidents attached to it, beside the component on the diagram.

Link an incident.io Catalog entry to the stratum for a service or component, and
the tab shows the incidents that named it. Link an incident instead, and the tab
explains one response: its lifecycle, severity, measured durations and follow-up
state. Responding and writing up stay in incident.io.

## Connect

1. You need an Enterprise licence, edit access to the blueprint, and
   `continuum_integrations.manage` on the connection's organisation or team.
2. In incident.io, create a dedicated key under **Settings → API keys** with
   **View data** (`viewer`) and **View catalog** (`catalog_viewer`). Leave write
   permissions and **View all incident data** (`global_access`) disabled.
3. In Blueprintr, open **Settings → Continuum**, go to **Operational
   integrations**, choose **New integration**, and select incident.io as the
   **Type**.
4. Paste the key into **API key**, set any of the optional fields below, and
   choose **Connect & verify**.

Verification reads the key's identity, one incident, the Catalog type list, one
Catalog entry, the custom-field list when relationship fields are configured, and
one follow-up when remediation counts are on. All requests are reads against
`api.incident.io`.

### Optional connection settings

Every field can be left blank. The three list fields accept up to 50
comma-separated IDs each. Ask your incident.io administrator for the stable IDs.

| Field | Blank behaviour | What it changes |
| --- | --- | --- |
| **Catalog types to search** | Searches available types within the retrieval budget | Restricts search to the service or component types your diagrams use |
| **Incident relationship fields** | An incident counts if it selects the entry in any custom field | Counts an incident only when it selects the entry in the listed fields, such as Affected services |
| **Catalog details to share** | No attributes are shown at all | Adds selected structured attributes, such as owning team or tier, visible to every blueprint reader |
| **Recent incident history (days)** | 30 | The window for the "created in the last N days" count. Accepts 1 to 90 |
| **Include remediation counts** | Off | Adds aggregate follow-up state. Needs the `actions.view` permission and the matching incident.io entitlement |

Active, triage and paused incidents are checked regardless of age, so the history
window only bounds the recent-history count.

## Link an object

Open the stratum, choose **Continuum Link**, and search. Once an incident.io
connection is in play, an **incident.io objects** selector appears with
**Catalog and incidents**, **Catalog records** and **Incidents**. Search a name,
a stable ID, an INC number or an incident link.

| What you type | What it finds |
| --- | --- |
| A name | Catalog entries, incidents, or both, depending on the selector |
| `INC-1042` or a bare number | That incident directly, including one older than the history window |
| A 26-character ULID or a UUID | That record directly |
| An `app.incident.io` incident link | That incident directly |

Typing `catalog:` or `incident:` in front of a query narrows it the same way the
selector does.

## What is always excluded

Blueprintr applies its own filter before anything reaches a panel, whatever the
key is permitted to read.

- An incident appears only when incident.io marks it organisation-visible and its
  mode is standard or retrospective. Private, test, tutorial and stream incidents
  never appear. Linking one returns "incident.io incident is private,
  unavailable, or a test record and cannot be linked."
- A Catalog type that represents people or customers is dropped, whether by its
  category or by user, person, customer, contact or employee appearing as a word
  in its name. Linking an entry of that type fails, but the reason is not shown. The editor sees
  the generic "incident.io could not be reached", so check the type's category and
  name before suspecting the connection.
- Only three shapes of Catalog attribute can be shared: numeric, boolean, and a
  relationship to a team, service or product-feature type. Free text is excluded.
  An attribute whose name suggests a secret, a token, an email address or a phone
  number is excluded even when its type is numeric, and selecting it fails
  verification.

Approved attribute values are clamped further: at most 10 records per attribute,
numbers must parse as numbers, and a relationship label must be 160 characters or
fewer with no line break and nothing shaped like an email address.

## What a Catalog panel shows

| Section | Contents |
| --- | --- |
| Catalog entry | Name, Type, ID, External ID, Catalog state, Updated |
| Related incidents | Active, Triage, Paused, created in the last N days, Coverage, Relationship |
| Approved Catalog relationships and metadata | The attributes you selected, or nothing when none are configured |
| Related incident details | Up to 10 incidents, open first and then newest first |

The Coverage row states the limit of the reading: "Organization-visible standard
and retrospective incidents only; private records are excluded. A related
incident does not by itself establish component health."

The headline is one of: "Archived Catalog entry", "Related incident coverage
incomplete", a count of related active incidents, a triage and paused count, or
"No related active incidents in available scope".

## What an incident panel shows

Reference, lifecycle, status, severity, whether a lead is assigned, and created
and updated times. The lead row reads Assigned, Unassigned or Unknown, and never
names the person. Below that sit measured durations with their availability, the
incident's timestamps, and links out to the incident, the postmortem and any
linked issue.

With remediation counts on, a **Follow-ups** section adds outstanding, completed,
not-doing and unknown-status totals. Descriptions and assignees are not imported.

## Partial results

Retrieval is bounded. When a page limit or budget is reached, counts are prefixed
"At least", the panel adds a coverage-incomplete section, and the snapshot is
marked partial. A count from a partial read is a lower bound, never a total.

Common messages an editor sees:

- "incident.io needs Catalog read access. Ask the connection owner to enable
  catalog_viewer and Verify in Settings → Continuum."
- "incident.io needs actions.view access for remediation counts. Enable that read
  permission or turn off remediation counts, then Verify."
- "incident.io results are incomplete. Narrow the Catalog types or search scope,
  then retry; open incident.io for the full view."
- "incident.io request limit reached. Wait a minute, then retry."

## Audience and refreshing

incident.io declares no audience setting, so its saved panel reaches everyone who
can read the stratum, including anonymous readers of a public blueprint. Incident
references, names, severities and any approved Catalog attributes are visible to
them. In incident.io, organisation-visible does not mean suitable for the public,
so review a record before linking it.

Snapshots become due for refresh after five minutes, as a reminder rather than
automatic polling. A failed refresh keeps the previous snapshot with a warning.
Changing a setting applies to later fetches and does not rewrite copies already
saved or shared.