Create an incident

Creates an incident with severity, routing, an optional monitor, alert channels and reporter context.

POST https://app.upfour.io/v1/incidents

A real request. Sending it changes data in your up4 account.

Authorization

AuthorizationA pls_ key. It stays in this browser tab. Needs incident.write.

Body

titlerequired

severity Defaults to critical.

description monitor_id The monitor the incident is about. Without one the incident is company-level, unless the escalation policy belongs to a client.

Routing3

routing_type everyone (default) or escalation_policy, which needs routing_target_id. Any other value, team included, is read as everyone.

routing_target_id The escalation policy for routing_type escalation_policy; must equal escalation_policy_id when both are given. escalation_policy_id Shortcut for routing_type escalation_policy with this policy as the target.

Alert channels1

notify Defaults to true. Set false to record the incident without alerting anyone: nothing goes out through alert channels or alert plans (email, SMS, voice, chat). The live view in the app and the outbound incident.opened webhook event still fire. With notify: false, escalation_policy_id, routing_type: escalation_policy, notification_channel_ids and override_channel_ids are rejected with 400, because each of them pages people.

Incident context2

cause Defaults to "Reported manually". reporter_email Kept in the payload of the opening timeline entry.

2 more fields are only available in JSON.

Headers

Idempotency-KeyheaderGenerated automatically when empty. How it works

Sent directly from your browser to https://app.upfour.io/v1. Mutating calls get an automatic Idempotency-Key when the field is empty.

Request

Responsenot sent yet

Fill in a key and press Send request (⌘↵).
The answer appears here.

scope incident.write stable Idempotency-Key supported returns 201

Body

The 4 fields most calls use come first; the rest are grouped below.

application/json required 12 fields

titlestringrequired

In the app: Brief description

severitystring

Defaults to critical.

criticalwarninginfo

In the app: Severity

descriptionstring

In the app: In-depth description

monitor_iduuid · nullable

The monitor the incident is about. Without one the incident is company-level, unless the escalation policy belongs to a client.

In the app: Affected monitor (optional)

Routing3 fields

routing_typestring

everyone (default) or escalation_policy, which needs routing_target_id. Any other value, team included, is read as everyone.

everyoneescalation_policy

routing_target_iduuid · nullable

The escalation policy for routing_type escalation_policy; must equal escalation_policy_id when both are given.

escalation_policy_iduuid · nullable

Shortcut for routing_type escalation_policy with this policy as the target.

Alert channels3 fields

notifyboolean · nullable

Defaults to true. Set false to record the incident without alerting anyone: nothing goes out through alert channels or alert plans (email, SMS, voice, chat). The live view in the app and the outbound incident.opened webhook event still fire. With notify: false, escalation_policy_id, routing_type: escalation_policy, notification_channel_ids and override_channel_ids are rejected with 400, because each of them pages people.

notification_channel_idsuuid[]

Alert channels to notify instead of the default routing; each must be visible to the caller and, for a client channel, belong to the incident's client.

override_channel_idsuuid[]

Same as notification_channel_ids; only read when that list is empty.

Incident context2 fields

causestring

Defaults to "Reported manually".

reporter_emailstring

Kept in the payload of the opening timeline entry.

Returns

A successful request returns 201 with application/json.

Response fields 1 top-level fields

Field Type Description

data IncidentDetail

IncidentDetail · 60 fields

Field Type Description

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 keyseach 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

Field	Type	Description
`attempt_count`	integer · nullable
`channel_name`	string
`created_at`	string (date-time)
`event_type`	string
`provider`	string
`status`	string one of`deliveredin_progresscancellednot_sentfailedunknown`
`channel_id`	uuid
`notice_kind`	string one of`initialreminderescalation`
`reason_code`	string one of`notification_policydo_not_disturbinitial_not_acceptednot_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 ofeveryoneescalation_policyteam

severity string one ofcriticalwarninginfo

started_at string (date-time)

started_by_type string

started_by_user_id uuid · nullable

status string one ofopenacknowledgedresolved

title string

updated_at string (date-time)

updates IncidentUpdate[] · nullable

Each item · 11 fields

Field	Type	Description
`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 ofnobodychannel_countchannel_count_with_policyname

escalation_target_name string

notified_channel_count integer

notified_kind string one ofnobodydelivery_failedchannel_countchannel

Errors

Only the errors this operation can return. Every error uses the same envelope.

Status	Code	Meaning
400	`bad_request`	The request is malformed or fails validation.
404	`not_found`	The requested resource does not exist or is outside the caller's scope.
403	`permission_denied`	The credentials do not permit this action.
400	documented response	The body is invalid, or `notify: false` is combined with an escalation policy or with notification channels (`notify cannot be false when an escalation policy is set: an alert plan pages people`, `notify cannot be false when notification channels are selected`).

Every call can also return unauthorized (401), rate_limit_exceeded (429) or internal_error (500 / 502). See Responses and errors.

curl -s -X POST "https://app.upfour.io/v1/incidents" \ -H "Authorization: Bearer $UP4_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "description": "Response times above 2 seconds since 08:40.", "escalation_policy_id": "00000000-0000-4000-8000-000000000002", "monitor_id": "00000000-0000-4000-8000-000000000001", "severity": "warning", "title": "Checkout is slow" }'

const res = await fetch("https://app.upfour.io/v1/incidents", { method: "POST", headers: { Authorization: `Bearer ${process.env.UP4_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ description: "Response times above 2 seconds since 08:40.", escalation_policy_id: "00000000-0000-4000-8000-000000000002", monitor_id: "00000000-0000-4000-8000-000000000001", severity: "warning", title: "Checkout is slow", }), }); console.log(res.status, await res.json());

import os import requests res = requests.post( "https://app.upfour.io/v1/incidents", headers={"Authorization": f"Bearer {os.environ['UP4_API_KEY']}"}, json={ "description": "Response times above 2 seconds since 08:40.", "escalation_policy_id": "00000000-0000-4000-8000-000000000002", "monitor_id": "00000000-0000-4000-8000-000000000001", "severity": "warning", "title": "Checkout is slow", }, ) print(res.status_code, res.json())

package main import ( "fmt" "io" "net/http" "os" "strings" ) func main() { payload := strings.NewReader(`{ "description": "Response times above 2 seconds since 08:40.", "escalation_policy_id": "00000000-0000-4000-8000-000000000002", "monitor_id": "00000000-0000-4000-8000-000000000001", "severity": "warning", "title": "Checkout is slow" }`) req, _ := http.NewRequest("POST", "https://app.upfour.io/v1/incidents", 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 $payload = <<<'JSON' { "description": "Response times above 2 seconds since 08:40.", "escalation_policy_id": "00000000-0000-4000-8000-000000000002", "monitor_id": "00000000-0000-4000-8000-000000000001", "severity": "warning", "title": "Checkout is slow" } JSON; $ch = curl_init("https://app.upfour.io/v1/incidents"); curl_setopt_array($ch, [ CURLOPT_CUSTOMREQUEST => "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);

{ "data": { "acknowledged_at": null, "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-000000000003", "metadata": {}, "monitor_id": "00000000-0000-4000-8000-000000000001", "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-000000000002", "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": "open", "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": "created", "id": "00000000-0000-4000-8000-000000000005", "incident_id": "00000000-0000-4000-8000-000000000003", "message": "Incident reported manually.", "message_code": "incident_created_manual", "payload": {} } ], "user_id": "00000000-0000-4000-8000-000000000004" } }