Create timeline entry — StatusDashboard Docs

POST /app/events/{id}/timeline

Adds a new timeline entry to the event and updates the event's current status. Returns the full updated event object.

Timeline entries apply to incidents and maintenance events only. Informational events do not have a timeline.

Path parameters

Parameter	Description
`id`	The event ID.

Request

See API Basics for required headers.

Request body

Field	Type	Required	Description
`statusLabel`	string	Yes	A workflow phase label valid for this event type.
`message`	string	Yes	The status message. Rich text field. See Rich text fields. Max 5,000 characters.
`timestamp`	string	No	ISO 8601 UTC datetime. Defaults to the current time. Cannot be in the future. Use this to record an update that happened before you were able to post it.

Sample request

curl -X POST https://api.statusdashboard.com/app/events/4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789/timeline \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "statusLabel": "Identified",
    "message": "Root cause identified as a misconfigured load balancer rule. Fix is being deployed."
  }'

Sample response

Status: 201 Created

{
  "event": {
    "id": "4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789",
    "eventType": "incident",
    "title": "API latency elevated",
    "status": { "label": "Identified", "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" }
      }
    },
    "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.",
        "author": "user@example.com",
        "isEdited": false
      },
      {
        "statusId": "9d1a4f7b-2c5e-4f8b-a1c3-d4e5f6789012",
        "timestamp": "2026-04-25T10:20:00.000Z",
        "status": { "label": "Identified", "description": "Root cause has been identified.", "color": "#f97316", "icon": "alert-circle" },
        "message": "Root cause identified as a misconfigured load balancer rule. Fix is being deployed.",
        "author": "user@example.com",
        "isEdited": false
      }
    ],
    "notes": [],
    "createdAt": "2026-04-25T09:58:00.000Z",
    "updatedAt": "2026-04-25T10:20:00.000Z"
  },
  "message": "Status update added successfully"
}

Incident end times and resolve time: When the status matches a final workflow phase (e.g. "Resolved"), two timestamps are set.

endTime is set to the timeline entry's timestamp. A custom (backdated) timestamp updates endTime to that value — not the clock time when you submitted the request. This is the interval end used for uptime and calendar-day views.

resolvedAt is set once when the event first becomes final (typically the time of this request). It is not rewritten to a custom timestamp, and it is cleared if you reopen the incident later.

endTime and resolvedAt can therefore differ when you backdate the final timeline entry. Public Event History orders and filters by when the event was marked final (resolvedAt), not by endTime.

When the event's notifications field is true, a new timeline entry may enqueue subscriber notifications asynchronously. See Event notifications.

Resolved incidents: Once an incident is resolved, you cannot add a non-final status via this endpoint. Use POST /app/events/{id}/reopen instead. Maintenance events may still be updated via timeline when completed.

Error responses

Status	When
`400`	Validation error — invalid status label, message too long, timestamp in the future, event type does not support timelines, or a resolved incident must be re-opened via `/reopen`.
`403`	Insufficient permissions.
`404`	Event not found.