# Update workflows

Replace the entire workflow phase configuration for incident and maintenance events.

Source: https://statusdashboard.com/docs/api/event-management/workflows/update

`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](/docs/api) for required headers.

### Request body
Both workflow types are required on every request.

```json
{
  "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](/docs/events/workflows#phase-fields).                                                                                                                        |
| `[].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](/docs/events/workflows#default-phases)).

```bash
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).

```json
{
  "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.               |