Custom fields

Custom fields let you capture the data your team cares about on every incident, things like affected services, impacted environment, or customer segment. You define a field once in Settings → Custom Fields, then attach it to one or more of the incident forms so responders fill it in at the right moment.

Field types

Click Add field to create a field. Give it a name, an optional description that responders see as help text, and pick a type:

Type	Best for
Text	Short or long-form text input
Number	Numeric input for counts or estimates
Link	An external reference URL
Single-select	One choice from a curated set
Multi-select	Multiple choices from a curated set
Catalog reference	Selecting one catalog entry
Catalog multi-reference	Selecting multiple catalog entries

Each field gets a stable key derived from its name. The key is shown next to the field in the list and does not change afterward, so integrations and reports can rely on it even if you rename the field.

Option sources

Select and reference fields need a source for their options:

Option source	How it works
Fixed list	You add the options yourself, one input per option
From catalogue	Options come from a catalog type you pick, such as Services or Teams

Text, number, and link fields take free input and have no options. Single-select and multi-select fields can use either a fixed list or a catalog type. Catalog reference and catalog multi-reference fields always draw from a catalog type.

Tip

Prefer catalog-backed options over fixed lists when the values represent real things like services or teams. The options stay in sync with your catalog automatically, the answers stay structured, which makes them far easier to report on later, and a long list stays manageable in a way a hand-typed one does not.

Choose the type before the field is used

A field’s type and option source can be changed freely up until the first incident stores a value in it. After that both lock, because changing them would reinterpret every answer already recorded. The two dropdowns grey out and hovering either one tells you how many incidents are involved.

Changing the type before that point clears the options, since a list written for one shape rarely fits another.

If a field in use turns out to be the wrong shape, turn it off and add a new one. The old field keeps its answers on the incidents that have them, and you attach the replacement to your forms. So it is worth a moment at creation deciding whether a value is really a number, a single choice, or several.

Where values get filled in

A custom field only appears to responders once you attach it to a form. There are four, one for each moment in an incident’s life:

Form	Opens with
Declare	/ff new
Update	/ff update
Resolve	/ff resolve
Cancel	/ff cancel

Each one also opens from the dashboard, so a field you attach is asked there too.

See Incident forms for how attaching, ordering, and required settings work.

Values captured this way appear on the incident page in the web dashboard in a Custom Fields panel, and they are included in the incident record that AI postmortem generation draws from.

Working with a fixed list

Each option in a fixed list gets its own input. Click Add option to add one, drag the handle to change the order responders see in the dropdown, and use the switch to turn an option off.

Renaming an option is safe at any time. Incidents that already hold it, and any runbook conditions that match on it, follow the new name. Nothing needs updating afterward.

Turning an option off removes it from the dropdown without touching the incidents that already hold it. Those keep showing the option and reading normally, responders just cannot pick it on new incidents. Turn it back on whenever you want it available again.

Deleting is only possible while nothing points at the option. Once an incident holds it or a runbook condition matches on it, Delete is disabled and hovering it tells you how many references there are. That count covers both, so an option no incident has ever used can still be held by a condition. Turn the option off instead, which is what you want in almost every case where a value has gone out of use.

Turning a field off, and deleting one

A field follows the same rule as its options, one level up.

Turning a field off stops it being collected without disturbing anything already recorded. It disappears from every form it is attached to, and the incidents holding values keep them. The switch in the Enabled column does this, and turning it back on puts the field back on the same forms.

Deleting a field is only possible while nothing depends on it. Delete is disabled while any form is attached to the field, and disabled again while any incident holds a value for it, because those answers are part of that incident’s history. Hovering tells you which of the two is blocking, and how many.

So a field that has been used in anger gets turned off rather than deleted. That is not a limitation to work around, it is what keeps a resolved incident readable a year later.

Managing fields

The list in Settings → Custom Fields shows every field with its key, its type, its catalog type if it has one, how many forms it is attached to, and whether it is enabled. The menu at the end of each row edits the field or deletes it.

Over the API and MCP

Fields can be created, changed and removed at /api/v1/custom_fields, and with the upsert_custom_field MCP tool. Options are matched by label, so resending a list renames rather than replaces, and the incidents already holding an option keep pointing at it. See Using the API.