Update workflows — StatusDashboard Docs

PUT /app/workflows

Replaces the entire workflows configuration for the organization. Requires the Custom Workflows plan feature.

The request body must include both incident and maintenance arrays — the stored configuration is fully replaced; missing fields are not merged from the existing record. The incident workflow must contain at least 2 phases; the maintenance workflow must contain at least 3 phases. the organization workflowPhases limit caps the maximum phase count. Phase labels must be unique within each workflow type (case-insensitive).

Phase marker and ordering rules

Final phase (incident and maintenance): Exactly one phase per workflow may be marked final. It must be the last phase in execution order (highest order value).

Planned / scheduled phase (maintenance only): Exactly one phase may be marked planned/scheduled. It must be the first phase in execution order (lowest order value). A phase cannot be both final and scheduled.

Maintenance minimum: At least 3 phases. With exactly one planned and exactly one final anchored at the ends, at least one active phase always sits between them.

Phases are stored and returned sorted by order ascending. Within each workflow array, order values must be unique and contiguous integers from 1 through the phase count (e.g. 3 phases require orders 1, 2, 3).

Request

See API Basics for required headers.

Request body

Both workflow types are required on every request.

{
  "incident": [
    {
      "label": "Investigating",
      "description": "Issue has been identified and investigation is underway to determine the root cause.",
      "color": "#D97706",
      "icon": "search",
      "order": 1,
      "isFinal": false
    },
    {
      "label": "Resolved",
      "description": "Issue has been fully resolved and all systems are operating normally.",
      "color": "#059669",
      "icon": "check-circle",
      "order": 2,
      "isFinal": true
    }
  ],
  "maintenance": [
    {
      "label": "Scheduled",
      "description": "Maintenance window has been scheduled and announced to users.",
      "color": "#2563EB",
      "icon": "clock",
      "order": 1,
      "isFinal": false,
      "isScheduled": true
    },
    {
      "label": "In Progress",
      "description": "Maintenance is currently underway and systems may be unavailable.",
      "color": "#CA8A04",
      "icon": "wrench",
      "order": 2,
      "isFinal": false
    },
    {
      "label": "Completed",
      "description": "Maintenance has been completed and all systems are back online.",
      "color": "#059669",
      "icon": "check-circle",
      "order": 3,
      "isFinal": true
    }
  ]
}

Field	Type	Required	Description
`incident`	array	Yes	Full replacement array for the incident workflow. At least 2 items; final phase must be last (`order` = highest). Subject to the organization `workflowPhases` limit.
`maintenance`	array	Yes	Full replacement array for the maintenance workflow. At least 3 items; scheduled phase must be first (`order` = lowest); final phase must be last (`order` = highest). Subject to the organization `workflowPhases` limit.
`[].label`	string	Yes	Display name. Must be unique within the array (case-insensitive). Max 50 characters.
`[].description`	string	Yes	Human-readable description. Max 150 characters.
`[].color`	string	Yes	Hex color string (e.g. `#059669`).
`[].icon`	string	Yes	Approved icon key. Must be one of the approved Lucide icons.
`[].order`	number	Yes	1-based integer, unique and contiguous from `1` through the phase count. Phases are stored and returned in this order.
`[].isFinal`	boolean	Yes	Set `true` on at most one phase per workflow to mark it as the terminal state.
`[].isScheduled`	boolean	No	Set `true` on at most one phase in the maintenance workflow to mark it as the initial scheduled state.

Sample request

Uses the seeded default labels, colors, and descriptions from new organizations (see Default phases).

curl -X PUT https://api.statusdashboard.com/app/workflows \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "incident": [
      { "label": "Investigating", "description": "Issue has been identified and investigation is underway to determine the root cause.", "color": "#D97706", "icon": "search",       "order": 1, "isFinal": false },
      { "label": "Identified",    "description": "Root cause has been identified and a fix is being implemented.",                         "color": "#6366F1", "icon": "alert-circle", "order": 2, "isFinal": false },
      { "label": "Monitoring",    "description": "Fix has been deployed and the system is being monitored to ensure stability.",             "color": "#0284C7", "icon": "eye",          "order": 3, "isFinal": false },
      { "label": "Resolved",      "description": "Issue has been fully resolved and all systems are operating normally.",                    "color": "#059669", "icon": "check-circle", "order": 4, "isFinal": true  }
    ],
    "maintenance": [
      { "label": "Scheduled",   "description": "Maintenance window has been scheduled and announced to users.",              "color": "#2563EB", "icon": "clock",        "order": 1, "isFinal": false, "isScheduled": true },
      { "label": "In Progress", "description": "Maintenance is currently underway and systems may be unavailable.",          "color": "#CA8A04", "icon": "wrench",       "order": 2, "isFinal": false },
      { "label": "Completed",   "description": "Maintenance has been completed and all systems are back online.",            "color": "#059669", "icon": "check-circle", "order": 3, "isFinal": true  }
    ]
  }'

Sample response

Status: 200 OK

The response body contains the stored configuration (phases sorted by order ascending).

{
  "message": "Workflows updated successfully",
  "workflows": {
    "incident": [
      { "label": "Investigating", "description": "Issue has been identified and investigation is underway to determine the root cause.", "color": "#D97706", "icon": "search",       "order": 1, "isFinal": false },
      { "label": "Identified",    "description": "Root cause has been identified and a fix is being implemented.",                         "color": "#6366F1", "icon": "alert-circle", "order": 2, "isFinal": false },
      { "label": "Monitoring",    "description": "Fix has been deployed and the system is being monitored to ensure stability.",             "color": "#0284C7", "icon": "eye",          "order": 3, "isFinal": false },
      { "label": "Resolved",      "description": "Issue has been fully resolved and all systems are operating normally.",                    "color": "#059669", "icon": "check-circle", "order": 4, "isFinal": true  }
    ],
    "maintenance": [
      { "label": "Scheduled",   "description": "Maintenance window has been scheduled and announced to users.",     "color": "#2563EB", "icon": "clock",        "order": 1, "isFinal": false, "isScheduled": true },
      { "label": "In Progress", "description": "Maintenance is currently underway and systems may be unavailable.", "color": "#CA8A04", "icon": "wrench",       "order": 2, "isFinal": false },
      { "label": "Completed",   "description": "Maintenance has been completed and all systems are back online.",   "color": "#059669", "icon": "check-circle", "order": 3, "isFinal": true  }
    ]
  }
}

Error responses

Status	When
`400`	Validation failed — see common messages below.
`400`	Missing required field (`incident` or `maintenance`)
`400`	`Incident workflow must have at least 2 phases`
`400`	`Maintenance workflow must have at least 3 phases`
`400`	`Incident workflow must have exactly one final phase` / `Maintenance workflow must have exactly one final phase`
`400`	`Maintenance workflow must have exactly one scheduled phase (e.g., Scheduled)`
`400`	`Only one phase can be marked as final`
`400`	`Only one phase can be marked as scheduled`
`400`	`Final phase must be the last phase in the workflow (highest order)`
`400`	`Scheduled phase must be the first phase in the workflow (lowest order)`
`400`	Phase order values must be unique, contiguous integers from 1 through the phase count
`400`	Duplicate labels, invalid icons, or incident phases marked `isScheduled`
`403`	Insufficient permissions, Custom Workflows feature not enabled, or `workflowPhases` limit reached.