Skip to main content

​
Overview

The web declare form accepts query parameters. Anything you pass is filled in before the responder sees the form, and everything stays editable — pre-filling chooses the starting point, it does not lock the answer. This turns any surface your team already uses into an incident entry point: a runbook link that arrives with the affected service selected, a monitoring alert whose “Declare incident” button carries the alert through, an internal tool that declares against a fixed environment.
Pre-filling changes the form’s initial state only. A responder can clear or change any pre-filled value before submitting, and required fields your form set enforces are still required. If a field fills automatically from another field that already has a value when the form opens, such as that field’s default, the automatic value replaces the one in the URL.

​
Supported Parameters

​
string
The incident title. URL-encode it — spaces become + or %20.
​
array of IDs
Services to select. Repeat the parameter for each one.
​
array of IDs
Functionalities to select. Repeat the parameter for each one.
​
array of IDs
Environments to select. Repeat the parameter for each one.
​
array of IDs
Teams to select. Repeat the parameter for each one.
​
array of IDs
Alerts to attach to the incident on creation. Use this when declaring from an alert so the alert travels with the incident.
​
ID
Declares the new incident as a sub-incident of this parent.
​
test | scheduled
The kind of incident to create. test declares a test incident; scheduled declares a scheduled maintenance incident. Omit it for a normal incident.
There is no preset_variables field for severity. A link that tries to set one is setting nothing, and the responder still picks a severity on the form. Build links that pre-fill the context — service, environment, team — and leave the judgement call to the person declaring.

​
Repeating Array Parameters

Parameters ending in [] take a list. Repeat the whole parameter once per value rather than separating values with commas:
A comma-separated value is read as a single ID and matches nothing.

​
Finding IDs

The *_ids[] parameters and parent_incident_id take Rootly IDs, not names. (preset_variables[title] and kind are plain values.) Settings pages show a name-based slug in the address bar, such as checkout-api, and the form matches IDs only, so read the id from the API:
  • From the API. List the collection and read the id of each record — GET /v1/services, GET /v1/functionalities, GET /v1/environments, GET /v1/teams. See Creating Incidents via API.
  • For alerts and incidents, whose IDs are not in a settings URL: GET /v1/alerts and GET /v1/incidents. In practice these are populated by whatever system builds the link — a monitoring tool that already knows the alert it fired — rather than by hand.
IDs are stable, so a link built once keeps working.

​
Pager Passthroughs

A “Declare incident” action inside a paging tool carries its context across using these, so your team does not have to build anything. They are listed here mainly so you recognise them in a URL you did not construct: Each pair carries the originating record’s identifier and a link back to it.

​
Worked Example

A runbook for the checkout service links to a declare form that already knows the service, the environment, and roughly what happened: Broken across lines so you can read it:
And as a single line, which is what you actually paste:
The responder opening that link sees a form with three fields already answered and picks the severity. The time saved is small; the consistency is not. Incidents declared from that runbook always carry the same service, environment, and owning team, which is what makes them comparable later in retrospectives and metrics.

Web Interface

The declare form itself — fields, validation, and what happens after submission.

API Creation

Creating incidents programmatically, and where to read the IDs these parameters need.