incident.io

Delete an alert note. via DELETE /v1/alert_notes/{id}

Delete an existing API key. The calling API key does not need to hold the scopes of the key being deleted, but a team-scoped key can only delete keys belonging to its teams. This endpoint requires a valid API key with the `api_keys_manage` role at either the account level or team level. via DELETE /v1/api_keys/{id}

Delete a custom field option via DELETE /v1/custom_field_options/{id}

Unattaches an external resource from an incident via DELETE /v1/incident_attachments/{id}

Delete an incident status via DELETE /v1/incident_statuses/{id}

Archive an incident template. Fails if the template is still referenced by an alert route. via DELETE /v1/incident_templates/{id}

Archives a maintenance window. Cannot archive active windows. via DELETE /v1/maintenance_windows/{id}

Delete a severity via DELETE /v1/severities/{id}

Delete an incident action. via DELETE /v2/actions/{id}

Destroy an alert attribute. via DELETE /v2/alert_attributes/{id}

Delete an existing alert route in your account. via DELETE /v2/alert_routes/{id}

Delete an existing alert source in your account. via DELETE /v2/alert_sources/{id}

Delete a custom field via DELETE /v2/custom_fields/{id}

Archives an escalation path. We recommend you create escalation paths in the incident.io dashboard where our path builder makes it easy to use conditions and visualise the path. via DELETE /v2/escalation_paths/{id}

Removes an existing role via DELETE /v2/incident_roles/{id}

Archive a policy. Archived policies stop evaluating and no longer appear in the API. via DELETE /v2/policies/{id}

Delete a schedule override, restoring whoever the rotations put on-call for that window. Deleting an override that has already been deleted succeeds, so it is safe to retry. via DELETE /v2/schedule_overrides/{id}

Archive a schedule sync target. Will fail if any active sync rules reference this target. via DELETE /v2/schedule_sync_targets/{id}

Archives a single schedule. Will fail if the schedule has active replicas — remove all replicas before deleting. via DELETE /v2/schedules/{id}

Archives a single schedule replica, stopping incident.io from syncing on-call shifts to the external provider. As with disabling mirroring via the UI, this will remove any upcoming overrides that incident.io has created in the external schedule, restoring it to its original state. If multiple replicas target the same external schedule, overrides are only removed when the last replica pointing to that schedule is deleted. Note: override cleanup is supported for PagerDuty and Jira Service Management. Opsgenie does not support programmatic override deletion, so overrides must be removed manually. via DELETE /v2/schedules/{schedule_id}/replicas/{id}

Archive a sync rule, unlinking the schedule from the sync target. via DELETE /v2/schedules/{schedule_id}/sync_rules/{id}

Delete a secret, permanently removing its value. Fails if the secret is still referenced by a workflow. via DELETE /v2/secrets/{id}

Archives a workflow via DELETE /v2/workflows/{id}

Delete an incident action. via DELETE /v3/actions/{id}

Delete an existing alert route in your account. via DELETE /v3/alert_routes/{id}

Archives a catalog entry. via DELETE /v3/catalog_entries/{id}

Archives a catalog type and associated entries. via DELETE /v3/catalog_types/{id}

Delete an incident follow-up. via DELETE /v3/follow_ups/{id}

List alert notes attached to an alert. via GET /v1/alert_notes

Get a single alert note. via GET /v1/alert_notes/{id}

List API keys visible to the calling API key, with pagination. An API key with account-level `api_keys_manage` access will see all keys, while a key with the `api_keys_manage` role scoped to specific teams will only see keys belonging to those teams. This endpoint requires a valid API key with the `api_keys_manage` role at either the account level or team level. via GET /v1/api_keys

Show details of a specific API key, including its roles, team assignments and when its token was last issued. This endpoint requires a valid API key with the `api_keys_manage` role at either the account level or team level. via GET /v1/api_keys/{id}

Show custom field options for a custom field via GET /v1/custom_field_options

Get a single custom field option via GET /v1/custom_field_options/{id}

Test if your API key is valid, and which roles it has. via GET /v1/identity

List all incident attachments for a given external resource or incident. You must provide either a specific incident ID or a specific external resource type and external ID. via GET /v1/incident_attachments

List related incidents for a specific incident. via GET /v1/incident_relationships

List all incident statuses for an organisation. via GET /v1/incident_statuses

Get a single incident status. via GET /v1/incident_statuses/{id}

List all incident templates for this organisation. via GET /v1/incident_templates

Show a single incident template. via GET /v1/incident_templates/{id}

List all incident types for an organisation. via GET /v1/incident_types

Get a single incident type. via GET /v1/incident_types/{id}

Show the IP allowlist for your organisation via GET /v1/ip_allowlists

List maintenance windows for your organisation. via GET /v1/maintenance_windows

Show a particular maintenance window. via GET /v1/maintenance_windows/{id}

Get the OpenAPI (v3) definition. via GET /v1/openapiV3.json

List post-mortem documents for the organisation. Results can be filtered by incident and sorted by creation date. This endpoint returns document metadata only. If you want to fetch the content of the post-mortem, use the ShowContent endpoint. via GET /v1/postmortem_documents

Get a single post-mortem document by ID. This returns the document's metadata. To retrieve the content of the post-mortem, use the ShowContent endpoint. via GET /v1/postmortem_documents/{id}

Fetch the content of a post-mortem document, rendered as markdown. The response contains the full document content as a single markdown string. The markdown follows standard formatting and is structured to mirror the post-mortem as it appears in the incident.io dashboard: - **Headings** (`#`, `##`, `###`) for document title and sections - **Bold** and *italic* text formatting - Bullet lists and numbered lists - [Links](url) to external resources, Slack threads, and pull requests - Mentions of users, incidents, and catalog entries resolved to their display names - Custom field values rendered as labelled bullet lists - Timeline entries grouped by date with timestamps - Follow-ups with assignees and descriptions To preview what this markdown will look like for a given post-mortem, open the document in the incident.io dashboard and use the "Copy to clipboard" button. The copied content uses the same rendering pipeline as this endpoint. If you only need document metadata, use the Show or List endpoints instead. via GET /v1/postmortem_documents/{id}/content

List all incident severities for an organisation. via GET /v1/severities

Get a single incident severity. via GET /v1/severities/{id}

List the linked Response incidents for a status page incident. via GET /v1/status-pages/{id}/incidents/{incident_id}/response-incidents

List all actions for an organisation. via GET /v2/actions

Get a single incident action. via GET /v2/actions/{id}

List alert attributes. via GET /v2/alert_attributes

Show an alert attribute. via GET /v2/alert_attributes/{id}

List all alert routes in your account. via GET /v2/alert_routes

Load details about a specific alert route in your account. via GET /v2/alert_routes/{id}

List all alert sources in your account. via GET /v2/alert_sources

Load details about a specific alert source in your account. via GET /v2/alert_sources/{id}

List all alerts for your account. This endpoint supports a number of filters, which can help find alerts matching certain criteria. These filters work similarly to the filters on the incidents endpoint, where a field is specified alongside a comparison operator in the query string. Note that: - Filters may be used together, and the result will be alerts that match all filters. - All query parameters must be URI encoded. ### By deduplication_key Find all alerts with deduplication_key ABC: curl --get 'https://api.incident.io/v2/alerts' \ --data 'deduplication_key[is]=ABC' ### By status Find all alerts in a firing state: curl --get 'https://api.incident.io/v2/alerts' \ --data 'status[one_of]=firing' ### By alert_source Find all alerts from a specific alert source (by alert source ID): curl --get 'https://api.incident.io/v2/alerts' \ --data 'alert_source[one_of]=01GBSQF3FHF7FWZQNWGHAVQ804' Find all alerts not from a specific alert source: curl --get 'https://api.incident.io/v2/alerts' \ --data 'alert_source[not_in]=01GBSQF3FHF7FWZQNWGHAVQ804' ### By alert_group_id Find all alerts in a specific alert group: curl --get 'https://api.incident.io/v2/alerts' \ --data 'alert_group_id[one_of]=01GBSQF3FHF7FWZQNWGHAVQ804' ### By created_at Find all alerts that follow specified date parameters for created_at field. Possible values are "gte" (greater than or equal to), "lte" (less than or equal to), and "date_range" (between two dates). The following example finds all alerts created after 2025-01-01: curl --get 'https://api.incident.io/v2/alerts' \ --data 'created_at[gte]=2025-01-01' To find alerts created within a specific date range, use the date_range option with tilde-separated dates: curl --get 'https://api.incident.io/v2/alerts' \ --data 'created_at[date_range]=2024-12-02~2024-12-08' ### By updated_at Find all alerts that follow specified date parameters for updated_at field, using the same "gte", "lte" and "date_range" operators as created_at. This is useful for incrementally syncing alerts: poll with updated_at[gte] set to your last sync time instead of re-fetching the full history. Note that updated_at moves whenever the alert row is written, which can happen without a visible change to the alert payload, so treat matches as candidates to re-fetch rather than guaranteed changes — and overlap your sync window by a few minutes to allow for writes that commit out of timestamp order: curl --get 'https://api.incident.io/v2/alerts' \ --data 'updated_at[gte]=2025-01-01T00:00:00Z' ### By has_notes Find all alerts that have notes attached: curl --get 'https://api.incident.io/v2/alerts' \ --data 'has_notes[is]=true' Find all alerts that have no notes attached: curl --get 'https://api.incident.io/v2/alerts' \ --data 'has_notes[is]=false' ### By attributes Alerts can be filtered by their attribute values. Each filter is keyed by the alert attribute ID, followed by an operator and the values to match. The accepted operators depend on the attribute's type. Find all alerts where attribute 01GBSQF3FHF7FWZQNWGHAVQ804 is one of two catalog entries: curl --get 'https://api.incident.io/v2/alerts' \ --data 'attributes[01GBSQF3FHF7FWZQNWGHAVQ804][one_of]=01GBSQF3FHF7FWZQNWGHAVQ804' \ --data 'attributes[01GBSQF3FHF7FWZQNWGHAVQ804][one_of]=01ET65M7ZARSFZ6TFDFVQDN9AA' You can filter on multiple attributes at once, and the result will be alerts that match all of them. ### Maintenance windows By default, all alerts are returned including those held by a maintenance window. To exclude alerts that are held by a maintenance window: curl --get 'https://api.incident.io/v2/alerts' \ --data 'include_maintenance_window[is]=false' via GET /v2/alerts

Show a single alert for your account via GET /v2/alerts/{id}

List Scribe call sessions, newest first, filtered by incident. via GET /v2/call_sessions

List transcript entries for a call session, oldest first. Returns an empty list if your organisation has disabled viewing transcripts. via GET /v2/call_transcript_entries

List all custom fields for an organisation. via GET /v2/custom_fields

Get a single custom field. via GET /v2/custom_fields/{id}

List all escalation paths in your account. An escalation path is a series of steps that describe how a page should be escalated, represented as a graph, supporting conditional branches based on alert priority and working intervals. via GET /v2/escalation_paths

Show an escalation path. We recommend you create escalation paths in the incident.io dashboard where our path builder makes it easy to use conditions and visualise the path. via GET /v2/escalation_paths/{id}

List all escalations for your account. This endpoint supports a number of filters, which can help find escalations matching certain criteria. Note that: - Filters may be used together, and the result will be escalations that match all filters. - All query parameters must be URI encoded. To use this API, you will need an API key with the "View data" or "Create and manage on-call resources" permission. ### By escalation_path Find all escalations that escalated to escalation path with id=ABC: curl --get 'https://api.incident.io/v2/escalations' \ --data 'escalation_path[one_of]=ABC' ### By status Find all escalations with a current status of "triggered": curl --get 'https://api.incident.io/v2/escalations' \ --data 'status[one_of]=triggered' Possible values are "pending", "triggered", "acked", "resolved", "expired" and "cancelled". Escalations are in "pending" when they are in a grace period when the related alert has been grouped in an incident. ### By alert Find all escalations that were created by alert with id=ABC: curl --get 'https://api.incident.io/v2/escalations' \ --data 'alert[one_of]=ABC' ### By incident Find all escalations related to incident with id=ABC: curl --get 'https://api.incident.io/v2/escalations' \ --data 'incident[one_of]=ABC' An escalation is related to an incident if it is linked to that incident directly, if it is attached to one of the incident's alerts, or if it triggered one of those alerts (which is what happens when someone pages by calling in, and that call raises the alert). To find everything that is not related to an incident, use "not_in": curl --get 'https://api.incident.io/v2/escalations' \ --data 'incident[not_in]=ABC' ### By created_at and updated_at Find all escalations that follow specified date parameters for created_at and updated_at fields. Possible values are "gte" (greater than or equal to), "lte" (less than or equal to), and "date_range" (between two dates). For example, to find all escalations updated after 2025-01-01: curl --get 'https://api.incident.io/v2/escalations' \ --data 'updated_at[gte]=2025-01-01' To find all escalations created between 2025-01-01 and 2025-01-31: curl --get 'https://api.incident.io/v2/escalations' \ --data 'created_at[date_range]=2025-01-01~2025-01-31' via GET /v2/escalations

Show a specific escalation. via GET /v2/escalations/{id}

List the activity log entries for an incident, oldest first. If the incident has streams, this returns their entries too, and incident_id on each entry tells you which stream it came from. Platform noise is left out: channel joins and leaves, chat messages and call transcript fragments are recorded internally but never returned here. via GET /v2/incident_activity_log_entries

List the connections between incidents and alerts via GET /v2/incident_alerts

List the participants of an incident with their workload. We calculate how much time each participant has spent working on the incident, aggregated per participant. Each participant is annotated with their participant type and, if they have left the incident, when they were archived. Workload is calculated periodically, so values can lag real time and the most recent period may still be filling. The metadata reports the time the figures are calculated up to. Workload for private incidents is only returned to API keys with the `incident_workloads.view_private` scope. via GET /v2/incident_participant_workloads

List the participants of an incident with the role they took. Participants are split into those who are actively helping with the incident and those who are just observing. Each participant is annotated with their participant type. via GET /v2/incident_participants

List all incident roles for an organisation. via GET /v2/incident_roles

Get a single incident role. via GET /v2/incident_roles/{id}

List the timeline items for an incident, oldest first. Items are ordered by timestamp, then by ID to break ties, which is the order the dashboard shows them in. If the incident has streams, this returns the items on its streams too - they're part of the same narrative - and incident_id on each item tells you which stream it came from. Items can be edited after they're written, and this endpoint always returns their current state, so listing an incident again gives you the timeline as it stands today. via GET /v2/incident_timeline_items

List all incident timestamps for an organisation. via GET /v2/incident_timestamps

Get a single incident timestamp. via GET /v2/incident_timestamps/{id}

List all incident updates for an organisation, or for a specific incident. via GET /v2/incident_updates

List all incidents for an organisation. This endpoint supports a number of filters, which can help find incidents matching certain criteria. Filters are provided as query parameters, but due to the dynamic nature of what you can query by (different accounts have different custom fields, statuses, etc) they are more complex than most. The maximum page size that can be requested is 250. To help, here are some exemplar curl requests with a human description of what they search for. Note that: - Filters may be combined using the filter_mode parameter: 'all' (default) requires all filters to match (AND logic), while 'any' requires at least one filter to match (OR logic). - IDs are normally in UUID format, but have been replaced with shorter strings to improve readability. - All query parameters must be URI encoded. ### By status With status of id=ABC, find all incidents that are set to that status: curl --get 'https://api.incident.io/v2/incidents' \ --data 'status[one_of]=ABC' Or all incidents that are not set to status with id=ABC: curl --get 'https://api.incident.io/v2/incidents' \ --data 'status[not_in]=ABC' ### By created_at or updated_at Find all incidents that follow specified date parameters for created_at and updated_at fields. Possible values are "gte" (greater than or equal to), "lte" (less than or equal to), and "date_range" (between two dates). The following example finds all incidents created before or on 2021-01-02T00:00:00Z: curl --get 'https://api.incident.io/v2/incidents' \ --data 'created_at[lte]=2021-01-02' To find incidents created within a specific date range, use the date_range option with tilde-separated dates: curl --get 'https://api.incident.io/v2/incidents' \ --data 'created_at[date_range]=2024-12-02~2024-12-08' ### By status category Find all incidents that are in a status category. Some categories use a different name in the API than the one shown in the dashboard — most notably "live" (shown as "Active") and "learning" (shown as "Post-incident"). The full mapping is: | API value | Shown in app as | | ---------- | --------------- | | triage | Triage | | live | Active | | learning | Post-incident | | paused | Paused | | closed | Closed | | declined | Declined | | canceled | Canceled | | merged | Merged | For example, to find all incidents the dashboard shows as "Active", filter on the "live" category: curl --get 'https://api.incident.io/v2/incidents' \ --data 'status_category[one_of]=live' Or all incidents that are not in a status category: curl --get 'https://api.incident.io/v2/incidents' \ --data 'status_category[not_in]=live' ### By severity With severity of id=ABC, find all incidents that are set to that severity: curl --get 'https://api.incident.io/v2/incidents' \ --data 'severity[one_of]=ABC' Or all incidents where severity rank is greater-than-or-equal-to the rank of severity id=ABC: curl --get 'https://api.incident.io/v2/incidents' \ --data 'severity[gte]=ABC' Or all incidents where severity rank is less-than-or-equal-to the rank of severity id=ABC: curl --get 'https://api.incident.io/v2/incidents' \ --data 'severity[lte]=ABC' ### By incident type With incident type of id=ABC, find all incidents that are of that type: curl --get 'https://api.incident.io/v2/incidents' \ --data 'incident_type[one_of]=ABC' Or all incidents not of that type: curl --get 'https://api.incident.io/v2/incidents' \ --data 'incident_type[not_in]=ABC' ### By incident mode By default, we return standard and retrospective incidents. This means that test and tutorial incidents are filtered out. To override this behaviour, you can use the mode filter to specify which modes you want to get. To find incidents of all modes: curl --get 'https://api.incident.io/v2/incidents' \ --data 'mode[one_of]=standard&mode[one_of]=retrospective&mode[one_of]=test&mode[one_of]=tutorial' To find just test incidents: curl --get 'https://api.incident.io/v2/incidents' \ --data 'mode[one_of]=test' ### By incident role Roles and custom fields have another nested layer in the query parameter, to account for operations against any of the roles or custom fields created in the account. With incident role id=ABC, find all incidents where that role is unset: curl --get 'https://api.incident.io/v2/incidents' \ --data 'incident_role[ABC][is_set]=true' Or where the role has been set: curl --get 'https://api.incident.io/v2/incidents' \ --data 'incident_role[ABC][is_set]=false' ### By option custom fields With an option custom field id=ABC, all incidents that have field ABC set to the custom field option of id=XYZ: curl \ --get 'https://api.incident.io/v2/incidents' \ --data 'custom_field[ABC][one_of]=XYZ' Or all incidents that do not have custom field id=ABC set to option id=XYZ: curl \ --get 'https://api.incident.io/v2/incidents' \ --data 'custom_field[ABC][not_in]=XYZ' ### Sorting By default, results are ordered by their creation date. You can use the sort_by parameter to reverse this order: curl \ --get 'https://api.incident.io/v2/incidents' \ --data 'sort_by=created_at_oldest_first' via GET /v2/incidents

Get a single incident. The ID supplied can be either the incident's full ID, or the numeric part of its reference. For example, to get INC-123, you could use either its full ID or: curl \ --get 'https://api.incident.io/v2/incidents/123 via GET /v2/incidents/{id}

List all policies for an organisation. via GET /v2/policies

Get a single policy. via GET /v2/policies/{id}

List the findings your policies have raised, whatever state they are in. via GET /v2/policy_findings

Get a single finding. via GET /v2/policy_findings/{id}

List the schedule entries for a schedule over a window of time. Use this endpoint to find out who is on-call for a schedule, either right now or at any point in the future. Common uses include: - Building a calendar or timeline view of who is on-call. - Looking up who was on-call at a particular moment (for example, when an incident fired). - Exporting upcoming shifts into another system, such as a payroll or scheduling tool. The response groups entries into three lists: `scheduled` (the entries the rotation rules produce, before any overrides), `overrides` (any one-off overrides that apply in the window) and `final` (the effective schedule after overrides have been merged in — this is normally the list you want). Each entry includes the `rotation_id` and `layer_id` it belongs to. Schedules can be made up of multiple rotations (for example, a primary and a secondary rotation) and each rotation can have several layers, and we return entries for every rotation and layer on the schedule. The endpoint returns all entries that overlap with the given window. If no window is provided we default to a sensible range starting from now. ## Pagination Responses are paginated. When more entries are available than fit on a single page, the response includes a `pagination_meta` block with two fields: - `after_url` — a fully-formed URL for the next page. The simplest way to paginate is to keep following this URL until it is no longer present. - `after` — an opaque cursor token. To fetch the next page manually, re-issue the request with `entry_window_start` set to this value and `entry_window_end` left unchanged from the original request. Treat the token as opaque — do not parse or modify it. Keep paginating until `pagination_meta` is absent from the response, at which point you have received every entry in the window. via GET /v2/schedule_entries

List the overrides on a schedule. Overrides are one-off changes layered on top of the rotations, such as someone covering a colleague's shift. This returns the overrides themselves: to see the effective schedule with overrides already merged in, use the schedule entries endpoint instead. Overrides belong to a specific layer of a specific rotation, so you can narrow the results with `rotation_id` and `layer_id`. Archived overrides are not returned. via GET /v2/schedule_overrides

Get a single schedule override. Overrides that have been deleted are not returned. An override's ID is not stable across edits: updating an override that overlaps its neighbours replaces them with new overrides, so an ID you are holding can stop resolving. List the schedule's overrides again to pick up the replacements. via GET /v2/schedule_overrides/{id}

List all schedule sync targets for this organisation. via GET /v2/schedule_sync_targets

Get a single schedule sync target. via GET /v2/schedule_sync_targets/{id}

List configured schedules. via GET /v2/schedules

Get a single schedule. via GET /v2/schedules/{id}

List all replicas for a schedule. via GET /v2/schedules/{schedule_id}/replicas

Get a single schedule replica. via GET /v2/schedules/{schedule_id}/replicas/{id}

List the sync rules configured on this schedule. via GET /v2/schedules/{schedule_id}/sync_rules

Get a single sync rule for a schedule. via GET /v2/schedules/{schedule_id}/sync_rules/{id}

List all secrets for this organisation. Returns metadata only, never values. via GET /v2/secrets

Show a single secret's metadata, including its version history. Never returns values. via GET /v2/secrets/{id}

List status page incidents. This endpoint requires a valid API key but no specific scopes. via GET /v2/status_page_incidents

Show a status page incident. This endpoint requires a valid API key but no specific scopes. via GET /v2/status_page_incidents/{status_page_incident_id}

List status page maintenances. This endpoint requires a valid API key but no specific scopes. via GET /v2/status_page_maintenances

Show a status page maintenance window. This endpoint requires a valid API key but no specific scopes. via GET /v2/status_page_maintenances/{status_page_maintenance_id}

Show the structure of a status page. This endpoint requires a valid API key but no specific scopes. Returns the components and component groups configured on a status page. Use this to find component IDs when specifying affected components for incidents or maintenance windows. via GET /v2/status_page_structures/{status_page_id}

List all status pages for your organisation. This endpoint requires a valid API key but no specific scopes. Use this to find status page IDs for use in other endpoints. via GET /v2/status_pages

List users in your account. via GET /v2/users

Get a single user. via GET /v2/users/{id}

List notification methods for a user. Phone numbers are partially redacted unless the API key holds the notification_methods.view_unredacted scope. via GET /v2/users/{user_id}/notification_methods

List notification rules for a user. Rules define how and when a user is notified for on-call pages. Only includes high_urgency and low_urgency rules; shift_changes rules are not returned. via GET /v2/users/{user_id}/notification_rules

Show the paging provider that would be used to escalate to this user. Reflects their explicit preference if set; otherwise resolves to the effective fallback (typically `native` for on-call seat users, or a linked external provider otherwise). May be omitted only when the user cannot be escalated to at all (no seat and no linked external user). via GET /v2/users/{user_id}/paging_provider

List workflow runs, newest first. Cancelled runs are never returned. The webhook delivery on each step omits the headers and bodies. Fetch a single run to see them. You can filter on when a run was created: ``` # Runs created on or after a date curl 'https://api.incident.io/v2/workflow_runs?created_at[gte]=2026-07-01' # Runs created on or before a date curl 'https://api.incident.io/v2/workflow_runs?created_at[lte]=2026-07-31' # Runs created between two dates curl 'https://api.incident.io/v2/workflow_runs?created_at[date_range]=2026-07-01~2026-07-31' ``` Paginate by passing the last run's ID as `after`. The response's `pagination_meta.after` carries the value to send next, and is absent on the last page. An `after` that isn't a run in your organisation returns 404. via GET /v2/workflow_runs

Show a single workflow run, including the full webhook delivery for any step that sent one. A delivery is kept for 7 days. After that `webhook_delivery_state` becomes `expired` and the delivery itself is absent: the step still ran and may well have succeeded, so an expired delivery must not be read as a failure. This may return a cancelled run, in which case `cancelled_at` is set. via GET /v2/workflow_runs/{id}

List all workflows via GET /v2/workflows

Show a workflow by ID via GET /v2/workflows/{id}

List actions for an organisation. Results are paginated and ordered by action ID, oldest first. Use the <code>after</code> value from <code>pagination_meta</code> to fetch the next page; it is only set when there may be more results. ### By created_at and updated_at Both timestamp filters accept the operators "gte" (greater than or equal to), "lte" (less than or equal to) and "date_range" (between two dates). The following example finds all actions updated after 2025-01-01: curl --get 'https://api.incident.io/v3/actions' \ --data 'updated_at[gte]=2025-01-01T00:00:00Z' To find actions created within a specific date range, use the date_range operator with tilde-separated dates: curl --get 'https://api.incident.io/v3/actions' \ --data 'created_at[date_range]=2024-12-02~2024-12-08' Filtering on updated_at is useful for incrementally syncing actions: poll with updated_at[gte] set to your last sync time instead of re-fetching the full history. Two caveats: updated_at moves whenever the action row itself is written, but changes to embedded objects (e.g. an assignee being renamed) can alter the payload without bumping it. And timestamps are stamped before commit, so an action can become visible with an older updated_at than rows you have already seen — overlap your sync window by a few minutes to allow for writes that commit out of timestamp order. via GET /v3/actions

Get a single incident action. via GET /v3/actions/{id}

List all alert routes in your account. via GET /v3/alert_routes

Load details about a specific alert route in your account. via GET /v3/alert_routes/{id}

List entries for a catalog type. via GET /v3/catalog_entries

Show a single catalog entry. via GET /v3/catalog_entries/{id}

List available engine resources for the catalog. A resource represents a type of data that can be held within the catalog, so this endpoint can be used to see what attribute types can be used when updating the schema of a catalog type. via GET /v3/catalog_resources

List all catalog types for an organisation, including those synced from external resources. via GET /v3/catalog_types

Show a single catalog type. via GET /v3/catalog_types/{id}

List follow-ups for an organisation. Results are paginated and ordered by follow-up ID, oldest first. Use the <code>after</code> value from <code>pagination_meta</code> to fetch the next page; it is only set when there may be more results. ### By created_at and updated_at Both timestamp filters accept the operators "gte" (greater than or equal to), "lte" (less than or equal to) and "date_range" (between two dates). The following example finds all follow-ups updated after 2025-01-01: curl --get 'https://api.incident.io/v3/follow_ups' \ --data 'updated_at[gte]=2025-01-01T00:00:00Z' To find follow-ups created within a specific date range, use the date_range operator with tilde-separated dates: curl --get 'https://api.incident.io/v3/follow_ups' \ --data 'created_at[date_range]=2024-12-02~2024-12-08' Filtering on updated_at is useful for incrementally syncing follow-ups: poll with updated_at[gte] set to your last sync time instead of re-fetching the full history. Two caveats: updated_at moves whenever the follow-up row itself is written, but changes to embedded objects (e.g. an assignee being renamed, or an external issue's status text) can alter the payload without bumping it. And timestamps are stamped before commit, so a follow-up can become visible with an older updated_at than rows you have already seen — overlap your sync window by a few minutes to allow for writes that commit out of timestamp order. via GET /v3/follow_ups

Get a single incident follow-up. via GET /v3/follow_ups/{id}

List all teams in the organisation. via GET /v3/teams

Get a single team. via GET /v3/teams/{id}

Edit a timeline item. Fields you leave out are unchanged, and an empty description removes it. Timestamp can only be changed on a custom item: a promoted one follows the activity it came from. via PATCH /v2/incident_timeline_items/{id}

Add a note to an alert. via POST /v1/alert_notes

Create a new API key. The calling API key can only assign roles whose scopes are a subset of its own. The `api_keys_manage` role cannot be assigned via the API. An organization can have a maximum of 5000 active API keys. This endpoint requires a valid API key with the `api_keys_manage` role at either the account level or team level. via POST /v1/api_keys

Rotate the access token for an API key. This generates a new bearer token and optionally keeps the old token valid for a configurable grace period (up to 60 minutes), allowing a seamless rollover without downtime. The calling API key must have all the scopes of the key being rotated. This endpoint requires a valid API key with the `api_keys_manage` role at either the account level or team level. via POST /v1/api_keys/{id}/actions/rotate

Create a custom field option. If the sort key is not supplied, it'll default to 1000, so the option appears near the end of the list. via POST /v1/custom_field_options

Attaches an external resource to an incident. You must provide a resource with resource_type and either external_id or url, but not both. When providing a url, the server will create the attachment from that link for the given resource type if the integration is installed and the link is valid. To attach an arbitrary link that isn't backed by an integration, use the arbitrary_url resource type with a url, and optionally a title and emoji. via POST /v1/incident_attachments

Makes a user a member of a private incident via POST /v1/incident_memberships

Revoke a user's membership of a private incident via POST /v1/incident_memberships/actions/revoke

Create a new incident status via POST /v1/incident_statuses

Create an incident template. via POST /v1/incident_templates

Check whether an incident template's config is valid, without creating or updating anything. This validates in the same way a create or update would: expressions are compiled and checked against your catalog. An invalid config is an error. A config that is valid but probably not what you meant — such as a name that's already taken — comes back as a warning on a successful response, so a client can show it without blocking. via POST /v1/incident_templates/actions/validate

Create a new maintenance window. via POST /v1/maintenance_windows

Link an externally-hosted post-mortem document to an incident. Use this to attach a retrospective document you've created in your own provider (for example Confluence, Notion, or Google Docs) to an existing incident. This is the API equivalent of pasting a document link into the incident.io dashboard, and is useful for automating your retrospective workflow - for example, creating a document in the right space with the right permissions when an incident is opened, then linking it back to the incident. Only one external post-mortem can be attached to an incident, and you cannot attach an external document to an incident that already has an in-app post-mortem. Re-attaching the same incident with a new permalink updates the existing link. via POST /v1/postmortem_documents/actions/attach

Create a new severity via POST /v1/severities

Create a new incident action. via POST /v2/actions

Create a new alert attribute. via POST /v2/alert_attributes

Create a new alert route in your account. via POST /v2/alert_routes

Create a new alert source in your account. via POST /v2/alert_sources

Check whether an alert source template is valid, without creating or updating anything. This validates the template in the same way a create or update would: expressions are compiled and checked against your alert schema and catalog, and merge strategies are checked against the attributes they bind to. Values that are only known once an alert source exists are not validated. via POST /v2/alert_sources/actions/validate

Resolve a currently firing alert. This marks the alert as resolved with the current time, attributing the resolution to the API key that made the request. Resolving an already-resolved alert is a no-op and returns the alert unchanged. Some alert sources are 'externally resolved' (for example, Datadog) — those alerts can only be resolved by the third-party system itself, and this endpoint will return a 422 explaining that. Private alerts: an API key without the 'view all alerts' scope can only resolve non-private alerts; private alerts will return a 404. Grant the API key a role that includes the global alerts access scope to resolve private alerts. via POST /v2/alerts/{id}/actions/resolve

Create a new custom field via POST /v2/custom_fields

Create an escalation path. An escalation path is a series of steps that describe how a page should be escalated, represented as graph, supporting conditional branches based on alert priority and working intervals. We recommend you create escalation paths in the incident.io dashboard where our path builder makes it easy to use conditions and visualise the path. via POST /v2/escalation_paths

Create an escalation. An escalation pages people, either according to an escalation path, or directly to specific users. You must provide either an escalation_path_id OR user_ids, but not both. When escalating via an escalation path, the escalation will follow the configured path with its levels and timeouts, using your default [alert priority](https://app.incident.io/~/settings/alerts/configuration/priorities). When escalating directly to users, they will receive a high-urgency notification, based on their notification rules. This endpoint is rate-limited to 60 requests per minute, since it is intended for interactive use cases (for example someone clicking a "escalate to team" button in your internal developer platform). To escalate based on automated alerts, we recommend sending events to an alert source instead. If your API key's permissions are scoped to teams, you can only escalate via an escalation path that one of those teams owns. Escalating directly to user_ids needs the permission at the account level, because an escalation aimed at a person has no owning team. via POST /v2/escalations

Check whether the given users can currently acknowledge, decline, or snooze an escalation. This is a read-only projection of the escalation's current state, intended for deciding which response actions to surface to each user in a custom integration. To use this API, you will need an API key that can view escalations and users. via POST /v2/escalations/{escalation_id}/actions/check_permissions

Respond to an escalation. An API key can acknowledge or snooze an escalation on its own, and the response is attributed to the key. Declining ("nack") means "I personally can't take this page", so it isn't available to an API key responding in its own right. To use this API, you will need an API key with the "Create and manage escalations" permission. via POST /v2/escalations/{escalation_id}/actions/respond

Cancel an escalation. Cancelling an escalation stops any further paging: notifications cease and the escalation will not advance to further levels or repeat. This works on escalations that are still paging (for example to silence a page when an incident is resolved before anyone acknowledges it) as well as snoozed ones. Escalations that have already resolved or expired cannot be cancelled, and cancelling an already-cancelled escalation is a no-op. To use this API, you will need an API key with the "Create and manage escalations" permission. via POST /v2/escalations/{id}/actions/cancel

Attach an alert to an incident, creating the connection between them. The API key also needs the 'manage incident alerts' scope, which is what actually relates the alert once the connection exists. If the alert is already related to this incident, the existing connection is returned unchanged. If someone previously marked the alert as unrelated to this incident, that decision is preserved and this endpoint returns a 422 — set re_relate to override it. Private alerts can only be attached to private incidents, including when re_relate is set. An API key that cannot see the alert or the incident receives a 404. Busy incidents can be locked by another operation, in which case this endpoint returns a 409 and the request can be retried. Note that this endpoint returns 201 even when it re-relates or returns an existing connection rather than creating a new one. via POST /v2/incident_alerts

Confirm or detach the connection between an alert and an incident. Set state to 'related' to confirm the connection, or 'unrelated' to detach the alert from the incident. The API key also needs the 'manage incident alerts' scope. A detached connection no longer appears in the list endpoint, which returns related connections only. Busy incidents can be locked by another operation, in which case this endpoint returns a 409 and the request can be retried. via POST /v2/incident_alerts/{id}/actions/transition

Create a new incident role via POST /v2/incident_roles

Add a custom item to an incident's timeline. Items created here are custom, so they carry no activity_log_id and their timestamp stays editable. Set it to when the thing actually happened rather than when you're telling us about it - a deploy you shipped an hour ago belongs an hour back on the timeline. Every request needs an idempotency_key. Retrying with a key we've already seen returns the item the first request created rather than writing a second one, so an automation that retries on a timeout doesn't leave a duplicate behind. via POST /v2/incident_timeline_items

Share an update against an incident. An update can carry a message, move the incident to a new status, change its severity, or any combination of the three. At least one of them must be provided. Which permissions you need depends on what the update does: changing status requires permission to update an incident's status, and changing severity permission to update its severity. via POST /v2/incident_updates

Create a new incident. Note that if the incident mode is set to "retrospective" then the new incident will not be announced in Slack. via POST /v2/incidents

Edit an existing incident. This endpoint allows you to edit the properties of an existing incident: e.g. set the severity or update custom fields. When using this endpoint, only fields that are provided will be edited (omitted fields will be ignored). The API key must have the scope corresponding to each property it changes: - `incidents.update_name` for the name - `incidents.update_summary` for the summary - `incidents.update_severity` for the severity - `incidents.update_status` for the status - `incidents.update_custom_fields` for custom fields - `incidents.update_timestamps` for timestamps - `incidents.update_role_assignments` for role assignments - `incident_calls.create` to set the call URL - `incident_calls.destroy` when replacing an existing call URL via POST /v2/incidents/{id}/actions/edit

Import a postmortem document from markdown into an incident. The document content should be provided as GitHub-Flavored Markdown. It will be parsed and converted into the collaborative editor format, and a new postmortem document will be created for the incident. If no main postmortem document exists for the incident, the imported document will become the main document. via POST /v2/incidents/{id}/actions/import_postmortem_document

Create a new policy. via POST /v2/policies

Dismiss a finding, so it stops being counted as open. Dismissing is a judgement that the finding doesn't need acting on, not that the resource now meets the policy. The finding stays queryable with a state of <code>dismissed</code>. via POST /v2/policy_findings/{id}/actions/dismiss

Undo a dismissal, returning the finding to its open state. via POST /v2/policy_findings/{id}/actions/restore

Create a new schedule override. via POST /v2/schedule_overrides

Create a new schedule sync target for a Slack user group. via POST /v2/schedule_sync_targets

Create a new schedule. via POST /v2/schedules

Preview the schedule entries that would be generated by a proposed schedule configuration. Use this endpoint before updating a schedule to see who would be on-call if you saved the supplied schedule payload. The request body uses the same `schedule` payload shape as Update schedule, so you can send the configuration you intend to save without persisting it. The response uses the same `schedule_entries` envelope as List schedule entries: `scheduled` contains entries produced by the rotation rules, `overrides` contains matching overrides, and `final` contains the effective schedule after overrides are applied. The preview window is bounded to keep requests predictable. If you ask for more than 91 days, the response is capped to 91 days from `entry_window_start`. via POST /v2/schedules/{id}/actions/preview_entries

Create a new schedule replica. via POST /v2/schedules/{schedule_id}/replicas

Create a new sync rule linking a schedule to a sync target. via POST /v2/schedules/{schedule_id}/sync_rules

Create a new secret with its initial value. via POST /v2/secrets

Rotate a secret's value, replacing the current value with a new one. The previous value is retired and can no longer be read. via POST /v2/secrets/{id}/actions/rotate

Post an update on a Status Page incident. This is the endpoint to use when resolving an incident - set incident_status to "resolved" to end the incident. There is a limit of 100 updates per incident. This endpoint requires an API key with the "Create status page incidents, status page maintenance windows, and publish status page updates" scope. via POST /v2/status_page_incident_updates

Create a status page incident. This endpoint requires an API key with the "Create status page incidents, status page maintenance windows, and publish status page updates" scope. via POST /v2/status_page_incidents

Post an update on a Status Page maintenance window. This is the endpoint to use when completing a maintenance window - set maintenance_status to "maintenance_complete" to end the maintenance. There is a limit of 100 updates per maintenance window. This endpoint requires an API key with the "Create status page incidents, status page maintenance windows, and publish status page updates" scope. via POST /v2/status_page_maintenance_updates

Schedule a Status Page maintenance window. This endpoint requires an API key with the "Create status page incidents, status page maintenance windows, and publish status page updates" scope. via POST /v2/status_page_maintenances

Create a retrospective (historical) status page incident. Use this to backfill a completed incident with a reconstructed timeline of past updates, for example when migrating from another status page provider. Every update's published_at must be in the past, the updates must be ordered chronologically (earliest first), and the final update must set incident_status to "resolved". Retrospective incidents never notify subscribers. As this endpoint is intended for bulk historical backfill, it has a dedicated rate limit of 5 requests per second (with a burst allowance of 300 requests) per API key. If you exceed it you'll receive a 429 response with a Retry-After header; back off and retry to resume your backfill. This endpoint requires an API key with the "Create status page incidents, status page maintenance windows, and publish status page updates" scope. via POST /v2/status_page_retrospective_incidents

Update a user's preferred paging provider. via POST /v2/users/{user_id}/paging_provider

Create a new workflow via POST /v2/workflows

Create a new incident action. via POST /v3/actions

Create a new alert route in your account. via POST /v3/alert_routes

Create an entry within the catalog. We support a maximum of 50,000 entries per type. If you call this API with a payload where the external_id and catalog_type_id match an existing entry, the existing entry will be updated. via POST /v3/catalog_entries

Update multiple catalog entries in a single operation. You can update up to 250 entries at once. This operation is atomic - either all entries are updated successfully, or none are updated. via POST /v3/catalog_entries/actions/bulk_update

Create a catalog type. The schema must be updated using the UpdateTypeSchema endpoint. via POST /v3/catalog_types

Update an existing catalog types schema, adding or removing attributes. Updating the schema is handled separately from creating and updating types, so that you don't have to worry about dependencies between types. For example, if type A has an attribute that relies on type B, you would have to create type B first. By allowing the creation of types without a schema, they can be created in any order, but it means that you need to make a separate call to this endpoint to update the schema. via POST /v3/catalog_types/{id}/actions/update_schema

Create a new incident follow-up. via POST /v3/follow_ups

Connect a follow-up to an existing issue in an issue tracker, using the URL of the issue. This will not work if the follow-up is already connected to an external issue. via POST /v3/follow_ups/{id}/actions/connect_external_issue

Replace the content of an alert note. via PUT /v1/alert_notes/{id}

Update an existing API key's name, roles, or team assignments. All fields must be provided (PUT semantics). The calling API key can only assign roles whose scopes are a subset of its own. An API key cannot edit itself, and the `api_keys_manage` role cannot be assigned via the API. This endpoint requires a valid API key with the `api_keys_manage` role at either the account level or team level. via PUT /v1/api_keys/{id}

Update a custom field option via PUT /v1/custom_field_options/{id}

Update an existing incident status via PUT /v1/incident_statuses/{id}

Update an incident template. This is a full replacement: any field not supplied is cleared. via PUT /v1/incident_templates/{id}

Update the IP allowlist for your organisation via PUT /v1/ip_allowlists

Update an existing maintenance window. via PUT /v1/maintenance_windows/{id}

Update the status of a post-mortem document. via PUT /v1/postmortem_documents/{id}

Update an existing severity via PUT /v1/severities/{id}

Update an existing incident action. via PUT /v2/actions/{id}

Update an alert attribute. via PUT /v2/alert_attributes/{id}

Update an existing alert route in your account. via PUT /v2/alert_routes/{id}

Update an existing alert source in your account. via PUT /v2/alert_sources/{id}

Update the details of a custom field via PUT /v2/custom_fields/{id}

Updates an escalation path. We recommend you create escalation paths in the incident.io dashboard where our path builder makes it easy to use conditions and visualise the path. via PUT /v2/escalation_paths/{id}

Update an existing incident role via PUT /v2/incident_roles/{id}

Update an existing policy. The <code>policy_type</code> of an existing policy cannot be changed: sending a different type is rejected. Create a new policy instead. via PUT /v2/policies/{id}

Update a schedule override, moving its window or the rotation and layer it sits on. An override cannot be reassigned: send the user it already has, and delete and recreate it to put someone else on call for that window. Overrides on a layer cannot overlap, so widening one over its neighbour's window takes that time over. The neighbour is deleted, and any of its time left outside the new window comes back as new overrides with new IDs, so other override IDs on this layer may stop resolving — list the schedule's overrides again to pick up the replacements. via PUT /v2/schedule_overrides/{id}

Update the add_bot_to_group flag on a sync target. The change propagates to every schedule with an active sync rule pointing at this target; the entire operation aborts if the caller lacks edit permission on any of those schedules. via PUT /v2/schedule_sync_targets/{id}

Update a schedule. Updating a schedule replaces its entire configuration with the one you send, including any scheduled future versions of its rotations — fetch the schedule first and include every version you want to keep. To change who's in a rotation from a future date without affecting shifts before then, keep the current version unchanged and add another version of the same rotation with `effective_from` set to when the change should land — ideally an upcoming handover, so nobody is swapped mid-shift. You can check the effect of any configuration before saving it with Preview schedule entries. via PUT /v2/schedules/{id}

Update a sync rule's sync_type and permanent members in place. If the rule's sync target is shared with other schedules, a sync_type change propagates to every linked schedule and the entire operation aborts if the caller lacks edit permission on any of them. Permanent members are scoped to this rule and never propagate. via PUT /v2/schedules/{schedule_id}/sync_rules/{id}

Update a secret's metadata. Does not change the value: use the rotate action for that. via PUT /v2/secrets/{id}

Update a status page incident. This endpoint requires an API key with the "Create status page incidents, status page maintenance windows, and publish status page updates" scope. via PUT /v2/status_page_incidents/{status_page_incident_id}

Update the credentials or configuration of a telemetry data source. Provide only the config block that matches your data source type (e.g. grafana_config for Grafana, datadog_config for Datadog). New credentials are validated against the provider before being saved. via PUT /v2/telemetry/data_sources/{id}

Updates a workflow via PUT /v2/workflows/{id}

Update an existing incident action. via PUT /v3/actions/{id}

Update an existing alert route in your account. via PUT /v3/alert_routes/{id}

Updates an existing catalog entry. via PUT /v3/catalog_entries/{id}

Updates an existing catalog type. The schema must be updated using the UpdateTypeSchema endpoint. via PUT /v3/catalog_types/{id}

Update an existing incident follow-up. via PUT /v3/follow_ups/{id}