# Add an incident update — API reference > Adds a message to the incident update stream and returns the updated incident detail. Source: https://upfour.io/docs/api/incidents/add-an-incident-update [Developers](https://upfour.io/docs/api.md)/[Incidents](https://upfour.io/docs/api/incidents.md) Adds a message to the incident update stream and returns the updated incident detail. POST https://app.upfour.io/v1/incidents/{incidentID}/updates scope incident.write stable [Idempotency-Key supported](https://upfour.io/docs/api/idempotency.md) returns 200 ## Parameters | Field | Type | Description | | --- | --- | --- | | `incidentID` required | uuid | path parameter | ## Body `application/json` required 2 fields messagestring (required) All other fields1 fields notifyboolean · nullable Defaults to true. Set false to add the comment without sending the `incident_comment` notification to alert channels. The comment is saved and the live view in the app updates either way. ## Returns A successful request returns `200` with application/json. Response fields 1 top-level fields | Field | Type | Description | | --- | --- | --- | | `data` | IncidentDetail | | | IncidentDetail · 60 fields FieldTypeDescription `acknowledged_at` string (date-time) · nullable `cause` string `check_method` string `check_url` string `client_id` uuid · nullable `correlated_count` integer `created_at` string (date-time) `created_by` string `description` string `duration_seconds` integer · nullable `escalation_target_label` string `heartbeat_id` uuid · nullable `heartbeat_name` string `id` uuid `metadata` map of string · nullable max 100 keys each value max length 4096 Custom key/value pairs (at most 100 keys; keys 1-128 characters, values up to 4096). Sent to machine-readable alert channels and API webhook subscriptions, and copied onto the incidents the resource opens. `monitor_id` uuid · nullable `monitor_name` string `notification_deliveries` IncidentNotificationDelivery[] · nullable Each item · 10 fields FieldTypeDescription `attempt_count` integer · nullable `channel_name` string `created_at` string (date-time) `event_type` string `provider` string `status` string one of`delivered` `in_progress` `cancelled` `not_sent` `failed` `unknown` `channel_id` uuid `notice_kind` string one of`initial` `reminder` `escalation` `reason_code` string one of`notification_policy` `do_not_disturb` `initial_not_accepted` `not_sent` `reminder_number` integer `notified_label` string `override_channel_ids` uuid[] · nullable `resolved_at` string (date-time) · nullable `resolved_by_type` string · nullable `resolved_by_user_id` uuid · nullable `routing_target_id` uuid · nullable `routing_type` string one of`everyone` `escalation_policy` `team` `severity` string one of`critical` `warning` `info` `started_at` string (date-time) `started_by_type` string `started_by_user_id` uuid · nullable `status` string one of`open` `acknowledged` `resolved` `title` string `updated_at` string (date-time) `updates` IncidentUpdate[] · nullable Each item · 11 fields FieldTypeDescription `actor_label` string `actor_type` string `actor_user_id` uuid · nullable `created_at` string (date-time) `event_type` string `id` uuid `incident_id` uuid `message` string `payload` object · nullable free-form keys `message_code` string Names a fixed system text of message so a client can translate it; empty for free text. `message_params` map of string Values for the message_code text. `user_id` uuid `escalation_target_channel_count` integer `escalation_target_kind` string one of`nobody` `channel_count` `channel_count_with_policy` `name` `escalation_target_name` string `notified_channel_count` integer `notified_kind` string one of`nobody` `delivery_failed` `channel_count` `channel` | | | ## Errors Only the errors this operation can return. Every error uses the [same envelope](https://upfour.io/docs/api/responses.md). | Status | Code | Meaning | | --- | --- | --- | | 400 | [bad_request](https://upfour.io/docs/api/errors#code-bad_request) | The request is malformed or fails validation. | | 404 | [not_found](https://upfour.io/docs/api/errors#code-not_found) | The requested resource does not exist or is outside the caller's scope. | | 403 | [permission_denied](https://upfour.io/docs/api/errors#code-permission_denied) | The credentials do not permit this action. | Every call can also return `unauthorized` (401), `rate_limit_exceeded` (429) or `internal_error` (500 / 502). See [Responses and errors](https://upfour.io/docs/api/responses.md). [PreviousGet an incident timeline](https://upfour.io/docs/api/incidents/get-an-incident-timeline.md) [NextList incident attachments](https://upfour.io/docs/api/incidents/list-incident-attachments.md) ## Request ### cURL ```bash curl -s -X POST "https://app.upfour.io/v1/incidents/00000000-0000-4000-8000-000000000001/updates" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "The provider confirms a partial outage." }' ``` ### JavaScript ```javascript const res = await fetch("https://app.upfour.io/v1/incidents/00000000-0000-4000-8000-000000000001/updates", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ message: "The provider confirms a partial outage.", }), }); console.log(res.status, await res.json()); ``` ### Python ```python import os import requests res = requests.post( "https://app.upfour.io/v1/incidents/00000000-0000-4000-8000-000000000001/updates", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "message": "The provider confirms a partial outage.", }, ) print(res.status_code, res.json()) ``` ### Go ```go package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "message": "The provider confirms a partial outage." }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/incidents/00000000-0000-4000-8000-000000000001/updates", payload) req.Header.Set("Authorization", "Bearer "+os.Getenv("UP4_API_KEY")) req.Header.Set("Content-Type", "application/json") res, err := http.DefaultClient.Do(req) if err != nil { panic(err) } defer res.Body.Close() out, _ := io.ReadAll(res.Body) fmt.Println(res.StatusCode, string(out)) } ``` ### PHP ```php "POST", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "Authorization: Bearer " . getenv("UP4_API_KEY"), "Content-Type: application/json", ], CURLOPT_POSTFIELDS => $payload, ]); $response = curl_exec($ch); echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $response, "\n"; curl_close($ch); ``` ## Response ### 200 ```json { "data": { "acknowledged_at": "2026-10-27T09:00:00Z", "cause": "Reported manually", "check_method": "GET", "check_url": "https://example.com", "client_id": null, "correlated_count": 0, "created_at": "2026-10-27T09:00:00Z", "created_by": "anna@example.com", "description": "Response times above 2 seconds since 08:40.", "duration_seconds": 0, "escalation_target_kind": "name", "escalation_target_label": "Default escalation", "escalation_target_name": "Default escalation", "heartbeat_id": null, "heartbeat_name": "", "id": "00000000-0000-4000-8000-000000000001", "metadata": {}, "monitor_id": "00000000-0000-4000-8000-000000000002", "monitor_name": "Marketing website", "notification_deliveries": [], "notified_kind": "nobody", "notified_label": "Nobody", "override_channel_ids": [], "resolved_at": null, "resolved_by_type": null, "resolved_by_user_id": null, "routing_target_id": "00000000-0000-4000-8000-000000000003", "routing_type": "escalation_policy", "severity": "warning", "started_at": "2026-10-27T09:00:00Z", "started_by_type": "user", "started_by_user_id": "00000000-0000-4000-8000-000000000004", "status": "acknowledged", "title": "Checkout is slow", "updated_at": "2026-10-27T09:00:00Z", "updates": [ { "actor_label": "anna@example.com", "actor_type": "user", "actor_user_id": "00000000-0000-4000-8000-000000000004", "created_at": "2026-10-27T09:00:00Z", "event_type": "comment", "id": "00000000-0000-4000-8000-000000000005", "incident_id": "00000000-0000-4000-8000-000000000001", "message": "The provider confirms a partial outage.", "payload": {} }, { "actor_label": "anna@example.com", "actor_type": "user", "actor_user_id": "00000000-0000-4000-8000-000000000004", "created_at": "2026-10-27T09:00:00Z", "event_type": "comment", "id": "00000000-0000-4000-8000-000000000006", "incident_id": "00000000-0000-4000-8000-000000000001", "message": "Looking into the payment provider.", "payload": {} }, { "actor_label": "anna@example.com", "actor_type": "user", "actor_user_id": "00000000-0000-4000-8000-000000000004", "created_at": "2026-10-27T09:00:00Z", "event_type": "escalation_target_acknowledged", "id": "00000000-0000-4000-8000-000000000007", "incident_id": "00000000-0000-4000-8000-000000000001", "message": "anna@example.com confirmed the manual escalation; the alert plan stopped", "payload": { "manual_escalation_id": "00000000-0000-4000-8000-000000000008", "source": "authenticated_user", "target_user_id": "00000000-0000-4000-8000-000000000004" } }, { "actor_label": "anna@example.com", "actor_type": "user", "actor_user_id": "00000000-0000-4000-8000-000000000004", "created_at": "2026-10-27T09:00:00Z", "event_type": "escalated", "id": "00000000-0000-4000-8000-000000000008", "incident_id": "00000000-0000-4000-8000-000000000001", "message": "Escalated to anna@example.com; the alert plan continues until they confirm", "payload": { "alert_plan_continues": true, "channel_ids": [ "00000000-0000-4000-8000-000000000009" ], "manual_escalation_id": "00000000-0000-4000-8000-000000000008", "manual_escalation_step": 1000001, "request_key": "walk-60", "status": "waiting_for_target_confirmation", "target_label": "anna@example.com", "target_user_id": "00000000-0000-4000-8000-000000000004" } }, { "actor_label": "anna@example.com", "actor_type": "user", "actor_user_id": "00000000-0000-4000-8000-000000000004", "created_at": "2026-10-27T09:00:00Z", "event_type": "created", "id": "00000000-0000-4000-8000-000000000010", "incident_id": "00000000-0000-4000-8000-000000000001", "message": "Incident reported manually.", "message_code": "incident_created_manual", "payload": {} } ], "user_id": "00000000-0000-4000-8000-000000000004" } } ``` ### 400 ```json { "error": { "code": "bad_request", "message": "The request is malformed or fails validation.", "request_id": "req_…" } } ``` ### 403 ```json { "error": { "code": "permission_denied", "message": "The credentials do not permit this action.", "request_id": "req_…" } } ``` ### 404 ```json { "error": { "code": "not_found", "message": "The requested resource does not exist or is outside the caller's scope.", "request_id": "req_…" } } ```