Skip to main content
POST
Create status page event

Restrictions

Usage

  • status and every component status in updates must be valid for type, and every component_id must exist on the page.
  • updates must be in non-decreasing at_seconds order. If status is resolved or completed, every affected component must end as operational.
  • With notify_subscribers: true, subscribers are notified once, about the last entry in updates.
  • For a maintenance with auto_update_by_schedule: true, the server moves it from scheduled to ongoing at start_at_seconds and from ongoing to completed at close_at_seconds, setting affected components back to operational.
  • Pass draft_id to publish a draft stored by POST /status-page/draft/create; the draft must target the same page and type and can be published only once.
  • Every call is recorded in the account audit log. Don’t put secrets in request fields.

Authorizations

app_key
string
query
required

APP Key created in the Flashduty console under My → APP Key. Send it as the app_key query parameter or in the Fd-App-Key request header. Its effective access is the intersection of the key's permission scope and the creator's current role permissions. Keep it secret.

Body

application/json

Parameters for creating a status page incident or maintenance event. The first update must contain component_changes to define affected components; retrospective events require at least 2 updates.

page_id
integer<int64>
required

Status page ID; obtain it from GET /status-page/list.

type
enum<string>
required

Change type: incident unplanned incident, maintenance planned maintenance.

Available options:
incident,
maintenance
title
string
required

Event title, up to 255 characters.

Maximum string length: 255
description
string
required

Event description (Markdown). Must not be empty.

status
enum<string>
required

Initial event status. investigating/identified/monitoring/resolved apply to incidents; scheduled/ongoing/completed apply to maintenances.

Available options:
investigating,
identified,
monitoring,
resolved,
scheduled,
ongoing,
completed
updates
object[]
required

Timeline updates in non-decreasing at_seconds order. At least one update is required, and at least one of them must contain component_changes. Immediate events normally pass one update; retrospective events must pass at least 2.

Minimum array length: 1
start_at_seconds
integer<int64>

Event start time in Unix seconds. Maintenances store this value as the scheduled start (with auto_update_by_schedule, the time the event switches to ongoing); when it is omitted or 0, and always for incidents, the start time is the first update's at_seconds.

responders
integer<int64>[]

Member IDs responsible for the event.

linked_changes
string[]

Linked change IDs (related incidents, deployments, etc.).

close_at_seconds
integer<int64>

Event close time in Unix seconds; must be greater than or equal to the first update's at_seconds. For maintenances this is the scheduled end; with auto_update_by_schedule the event switches to completed at this time, which must be within 30 days from now. For a retrospective event in a terminal status, omitting it uses the latest update's time.

notify_subscribers
boolean

Notify subscribers about this event. On creation one notification is sent for the last update; later timeline entries also notify while this is true.

auto_update_by_schedule
boolean

Maintenance only: automatically advance the status based on the scheduled window.

is_retrospective
boolean

Mark the event as retrospective (a past event recorded afterwards). Requires at least 2 entries in updates.

draft_id
string

ID of a draft created by POST /status-page/draft/create to publish with this event. The draft must be pending, target this page_id and type, and have no change_id; it is marked published once the event is created. Omit when not publishing a draft.

Response

Success

Success response envelope. On every 2xx response, request_id identifies the call (also mirrored in the Flashcat-Request-Id header) and data holds the endpoint-specific payload. Failure responses use a different shape — see ErrorResponse.

request_id
string
required

Unique ID for this request. Mirrored in the Flashcat-Request-Id response header. Include it when reporting issues.

Example:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

Result of creating a status page event.