Skip to main content

Incident workflow transitions

Incident states are controlled by the organization's workflow. Do not patch stateId directly: discover an available transition and execute it.

Organization External API keys use the OWNER role when transition permissions are evaluated. External API transitions are attributed to the organization's External API auditor.

List available transitions​

  • Method: GET
  • Endpoint: /incidents/{id}/available-transitions
  • Operation ID: list-available-incident-transitions
[
  {
    "id": "d130806e-4b83-4f9d-997c-95c493d2b18a",
    "fromStateId": "1e86aa2d-717a-46db-a73b-c760fb44869d",
    "toStateId": "6ca44588-8176-42cf-a5fd-ff48c3ff6cee",
    "name": "Start investigation",
    "active": true,
    "noteMode": "OPTIONAL",
    "roles": ["OWNER", "ADMIN"],
    "externalId": null
  }
]

noteMode is HIDDEN, OPTIONAL, or REQUIRED.

Execute a transition​

  • Method: POST
  • Endpoint: /incidents/{id}/transitions
  • Operation ID: execute-incident-transition
{
  "transitionId": "d130806e-4b83-4f9d-997c-95c493d2b18a",
  "note": "Maintenance team notified."
}

transitionId is required. note is nullable, has a maximum length of 2,000 characters, and must follow the transition's noteMode.

Success returns 200 OK with the updated IncidentResponse. A 403 Forbidden response means the transition is not allowed for the External API OWNER role.

Read transition history​

  • Method: GET
  • Endpoint: /incidents/{id}/transition-history
  • Operation ID: get-incident-transition-history
  • Query parameters: limit, offset, sort
{
  "data": [
    {
      "id": "14a6bd09-7633-4ae1-bfbd-fecba82ad3d9",
      "transitionId": "d130806e-4b83-4f9d-997c-95c493d2b18a",
      "fromStateId": "1e86aa2d-717a-46db-a73b-c760fb44869d",
      "toStateId": "6ca44588-8176-42cf-a5fd-ff48c3ff6cee",
      "note": "Maintenance team notified.",
      "changedBy": "b4b48940-d927-4d93-8a69-9e1a32ee96ca",
      "changedAt": "2026-08-13T10:05:00.000Z"
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 20,
    "count": 1,
    "sort": null,
    "filter": []
  }
}

Common errors for these endpoints are 401 Unauthorized, 404 Not Found, and 500 Internal Server Error.

changedBy identifies the user recorded for the transition. For an External API transition, it is the organization's External API auditor.