# Update timeline entry

Edit the message or timestamp of an existing timeline entry.

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

`PUT /app/events/{id}/timeline/{statusId}`

Replaces the editable fields on a timeline entry (`message` required; `timestamp` optional). Status and author cannot be changed. The entry is marked as `isEdited: true`. Uses **`PUT`** for this sub-resource — see [Documented PUT exceptions](/docs/api#documented-put-exceptions-sub-resources) in API Basics. Returns the full updated event object.

**Timestamp cascade (incidents only):** If a new `timestamp` is provided, editing the **first entry** (by insertion order) overwrites the incident's `startTime`. Editing the **last entry when its status is a final phase** (e.g. Resolved) overwrites the incident's `endTime`. No cascade occurs for maintenance or informational events.

***

## Path parameters
| Parameter  | Description            |
| ---------- | ---------------------- |
| `id`       | The event ID.          |
| `statusId` | The timeline entry ID. |

***

## Request
See [API Basics](/docs/api) for required headers.

### Request body
| Field       | Type   | Required | Description                                                                                                                                                                                 |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message`   | string | Yes      | Updated message text. Rich text field. See [Rich text fields](/docs/api#rich-text-fields). Max 5,000 characters.                                                                            |
| `timestamp` | string | No       | Updated ISO 8601 UTC datetime for this entry. Cannot be in the future. When changed on the first or final entry of an incident, the event's `startTime` or `endTime` updates automatically. |

***

## Sample request
```bash
curl -X PUT https://api.statusdashboard.com/app/events/4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789/timeline/7a3f9d2e-1b4c-4e8a-90b2-c3d4e5f67890 \
  -H "Authorization: Bearer bcf847abf5c6:def456" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "We are aware of elevated API response times and are actively investigating. Some users may experience timeouts.",
    "timestamp": "2026-04-25T09:30:00.000Z"
  }'
```

## Sample response
**Status: `200 OK`**

```json
{
  "event": {
    "id": "4f8b2e1a-3c7d-4e9f-a0b1-c2d3e4f56789",
    "eventType": "incident",
    "title": "API latency elevated",
    "status": { "label": "Investigating", "isFinal": false, "isScheduled": false },
    "startTime": "2026-04-25T09:30:00.000Z",
    "timeline": [
      {
        "statusId": "7a3f9d2e-1b4c-4e8a-90b2-c3d4e5f67890",
        "timestamp": "2026-04-25T09:30:00.000Z",
        "status": "Investigating",
        "message": "We are aware of elevated API response times and are actively investigating. Some users may experience timeouts.",
        "author": "user@example.com",
        "isEdited": true
      }
    ]
  },
  "message": "Timeline entry updated successfully"
}
```

*The `startTime` updated from `09:45` to `09:30` because this is the first entry of an incident and a new `timestamp` was provided.*

***

## Error responses
| Status | When                                                            |
| ------ | --------------------------------------------------------------- |
| `400`  | Validation error — message too long or timestamp in the future. |
| `403`  | Insufficient permissions.                                       |
| `404`  | Event or timeline entry not found.                              |
| `409`  | The event was modified concurrently; refresh and retry.         |