Create event — StatusDashboard Docs

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 — apply client-side before calling this endpoint.

Request

See API Basics 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. 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.
`segmentNotification`	object	No	Per-event segment include/exclude targeting. Requires the `segments` feature. See segmentNotification fields below.
`attributes`	array	No	Custom key/value metadata. See attributes fields below.
`coordinator`	object	No	Optional point of contact. See 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 for behavior details.

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.

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. 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. 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. Max 5,000 characters.
`maintenanceAutomation`	object	No	Automatic start/stop at `startTime` and `endTime`. Default: disabled. See maintenanceAutomation fields and Maintenance — Automatic start & stop.
`impactAnalysis`	string	No	Optional customer and service impact details. Rich text field. See 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.

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

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

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.

Sample response

Status: 201 Created

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

On this page