# Create event Create a new incident, maintenance window, or informational event. Source: https://statusdashboard.com/docs/api/event-management/events/create `POST /app/events` Creates a new event. The required fields vary by event type. To prefill playbook fields from a saved blueprint, see [Using a template](/docs/events/templates#using-a-template) — apply client-side before calling this endpoint. *** ## Request See [API Basics](/docs/api) for required headers. ### Common fields (all event types) | Field | Type | Required | Description | | --------------------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `eventType` | string | Yes | `"incident"`, `"maintenance"`, or `"informational"`. Cannot be changed after creation. | | `title` | string | Yes | Brief event title. Max 250 characters. | | `description` | string | Yes | Event description. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 5,000 characters. | | `publish` | boolean | No | Whether to publish immediately. Default: `false`. | | `notifications` | boolean | No | Whether matching subscribers are notified when this event changes. Default: `true`. Independent of `publish` — see [Event notifications](/docs/events/notifications). | | `segmentNotification` | object | No | Per-event segment include/exclude targeting. Requires the `segments` feature. See [segmentNotification fields](#segmentnotification-fields) below. | | `attributes` | array | No | Custom key/value metadata. See [attributes fields](#attributes-fields) below. | | `coordinator` | object | No | Optional point of contact. See [coordinator fields](#coordinator-fields) below. | ### segmentNotification fields Requires the organization `segments` feature. When omitted, segment targeting is disabled. | Field | Type | Description | | ------------ | --------- | ------------------------------------------------------------------------------------------------------------ | | `enabled` | boolean | Whether segment targeting is active for this event. | | `mode` | string | `"include"` or `"exclude"`. | | `segmentIds` | string\[] | UUIDs of org segments. Required (≥1) when `enabled` is `true` and `mode` is `"include"`. All IDs must exist. | See [Segment targeting](/docs/events/segments) for behavior details. ### attributes fields Optional custom metadata on the event. Max count per `limits.attributes` organization limit. | Field | Type | Description | | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | `key` | string | 1–32 characters. Must start with a letter; may contain letters, numbers, underscores, and hyphens. Unique per event. | | `value` | string | 1–256 characters. | | `isPublic` | boolean | `true` — shown on the status dashboard and in subscriber notifications. `false` — visible only in the event editor. | See [Attributes](/docs/events/attributes) for visibility behavior. ### Incident-specific fields | Field | Type | Required | Description | | ------------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `startTime` | string | No | ISO 8601 UTC datetime of when the incident began. Cannot be in the future. Defaults to the time of creation when omitted. | | `statusLabel` | string | Yes | Initial status phase from the incident workflow. | | `affectedComponents` | object | Yes | Map of `componentId → severityLabel`. At least 1 entry required. Event severity is **derived server-side** from the highest-order label in this map. | | `initialTimelineMessage` | string | Yes | First timeline entry message. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 5,000 characters. The first entry's timestamp is set to `startTime`, or the time of creation if `startTime` is omitted. | | `impactAnalysis` | string | No | Optional customer and service impact details. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 5,000 characters. | ### Maintenance-specific fields | Field | Type | Required | Description | | ------------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `startTime` | string | Yes | ISO 8601 UTC datetime. Scheduled start time; must be before `endTime`. | | `endTime` | string | Yes | ISO 8601 UTC datetime. Scheduled end time; must be after `startTime`. | | `statusLabel` | string | Yes | Initial status phase from the maintenance workflow. | | `affectedComponents` | object | Yes | Map of `componentId → severityLabel`. At least 1 entry required, max 50. Event severity is **derived server-side** from the highest-order label in this map. | | `initialTimelineMessage` | string | Yes | First timeline entry message. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 5,000 characters. | | `maintenanceAutomation` | object | No | Automatic start/stop at `startTime` and `endTime`. Default: disabled. See [maintenanceAutomation fields](#maintenanceautomation-fields) and [Maintenance — Automatic start & stop](/docs/events/types/maintenance#automatic-start--stop). | | `impactAnalysis` | string | No | Optional customer and service impact details. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 5,000 characters. | #### maintenanceAutomation fields Maintenance only. When omitted, automation is disabled. | Field | Type | Description | | ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | When `true`, the event automatically moves to the next active workflow phase at `startTime` and to the final phase at `endTime`. | | `advanceNotification` | object | Optional advance subscriber notice before start. Ignored when `enabled` is `false`. | | `advanceNotification.enabled` | boolean | When `true`, send one advance notification at `startTime − lead`. | | `advanceNotification.value` | integer | Lead amount. 1–9999. | | `advanceNotification.unit` | string | `"minutes"`, `"hours"`, or `"days"`. Default lead when advance is enabled: `24` hours. | | `startMessage` | string | Timeline message for auto-start. Rich text. Max 5,000 characters. Default: `"Maintenance has started as scheduled."` | | `stopMessage` | string | Timeline message for auto-stop. Rich text. Max 5,000 characters. Default: `"Maintenance has completed as scheduled."` | Transitions are evaluated at **minute** precision (seconds on `startTime` / `endTime` are stored but do not delay the trigger minute). Subscriber notifications follow the event's `notifications` setting. See [Maintenance — When transitions run](/docs/events/types/maintenance#when-transitions-run-minute-accuracy). ### Informational-specific fields Informational events support an optional `affectedComponents` field for subscriber notification routing. The `statusLabel`, `initialTimelineMessage`, and `impactAnalysis` fields are not applicable and will return a `400` if passed. Do not pass a top-level `severity` field — severity is derived only for incidents and maintenance from `affectedComponents`. | Field | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `affectedComponents` | object | No | Map of `componentId → ""`. Up to 50 entries. Component IDs must exist. Severity labels are not applicable — pass an empty string or omit the value. Component status is **not** changed by this field. | ### Coordinator fields All fields are optional. The `coordinator` object is omitted from the response when not set. | Field | Type | Max length | Description | | ----------- | ------ | ---------- | ----------------------------------------------------- | | `name` | string | 100 | Person's full name. | | `title` | string | 100 | Job title or role. | | `email` | string | 254 | Rendered as a `mailto:` link on the status dashboard. | | `phone` | string | 50 | Rendered as a `tel:` link on the status dashboard. | | `extraInfo` | string | 500 | Free-form context, e.g. on-call hours. | *** ## Sample request — incident ```bash curl -X POST https://api.statusdashboard.com/app/events \ -H "Authorization: Bearer bcf847abf5c6:def456" \ -H "Content-Type: application/json" \ -d '{ "eventType": "incident", "title": "API latency elevated", "startTime": "2026-04-25T09:45:00.000Z", "statusLabel": "Investigating", "affectedComponents": { "6b0d3a8c-5e2f-4b7d-9c1e-f23456789abc": "Degraded Performance" }, "description": "We are investigating elevated API response times affecting a subset of users.", "initialTimelineMessage": "We are aware of elevated API response times and are investigating the root cause.", "publish": true }' ``` ## Sample request — maintenance ```bash curl -X POST https://api.statusdashboard.com/app/events \ -H "Authorization: Bearer bcf847abf5c6:def456" \ -H "Content-Type: application/json" \ -d '{ "eventType": "maintenance", "title": "Database migration — 2026-05-01", "statusLabel": "Scheduled", "affectedComponents": { "8c1e4b7f-3a6d-4c9e-b2f1-a34567890bcd": "Degraded Performance" }, "description": "Scheduled database maintenance. Brief downtime expected.", "startTime": "2026-05-01T02:00:00.000Z", "endTime": "2026-05-01T04:00:00.000Z", "initialTimelineMessage": "Maintenance is scheduled for 2026-05-01 02:00–04:00 UTC.", "publish": true, "notifications": true, "maintenanceAutomation": { "enabled": true, "advanceNotification": { "enabled": true, "value": 24, "unit": "hours" } } }' ``` > When > `notifications` > is > `true` > , a successful create may enqueue subscriber notifications asynchronously. Delivery is non-fatal — the API response succeeds even if notification delivery is delayed. See > [Event notifications](/docs/events/notifications) > . ## Sample response **Status: `201 Created`** ```json { "event": { "id": "4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789", "eventType": "incident", "title": "API latency elevated", "status": { "label": "Investigating", "isFinal": false, "isScheduled": false }, "severity": { "label": "Degraded Performance", "description": "Some functionality is impaired.", "icon": "alert-triangle", "color": "#f59e0b" }, "affectedComponents": { "6b0d3a8c-5e2f-4b7d-9c1e-f23456789abc": { "name": "API Gateway", "status": { "label": "Degraded Performance", "description": "Some functionality is impaired.", "icon": "alert-triangle", "color": "#f59e0b" } } }, "description": "We are investigating elevated API response times affecting a subset of users.", "startTime": "2026-04-25T09:45:00.000Z", "publish": true, "notifications": true, "timeline": [ { "statusId": "7a3f9d2e-1b4c-4e8a-90b2-c3d4e5f67890", "timestamp": "2026-04-25T09:45:00.000Z", "status": { "label": "Investigating", "description": "We are looking into the issue.", "color": "#D97706", "icon": "search" }, "message": "We are aware of elevated API response times and are investigating the root cause.", "author": "user@example.com", "isEdited": false } ], "notes": [], "createdAt": "2026-04-25T10:00:00.000Z", "createdBy": "user@example.com", "updatedAt": "2026-04-25T10:00:00.000Z" } } ``` > Note that the first timeline entry's > `timestamp` > matches the incident's > `startTime` > . These two values are always in sync at creation. *** ## Error responses | Status | When | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Validation error — missing required field, invalid severity label, invalid workflow phase, invalid component IDs, `maintenanceAutomation` or `impactAnalysis` on a non-incident/maintenance event, advance-notification lead exceeds time until start, or (for maintenance with a future `startTime`) `statusLabel` is not the scheduled/planned phase. | | `403` | Insufficient permissions. |