upzero
Get startedGuidesCLIAPI
Endpoints

Incidents

List Incidents

GET/api/v1/me/incidents

List incidents for the authenticated organization with filtering and pagination.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Query Parameters

offset?Offset
Range0 <= value
Default0
limit?Limit
Range1 <= value <= 100
Default20
since?|

Time range: 7d, 24h, 1h, or ISO datetime

Default"7d"
search?string|null
severity?|null
status?|null
incident_type?string|null
monitor_id?|null
is_resolved?boolean|null
stats?Stats

Include unfiltered statistics

Defaultfalse

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/me/incidents"
null

Get Incident

GET/api/v1/me/incidents/{incident_id}

Get a single incident by ID.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08"
null

Patch Incident

PATCH/api/v1/me/incidents/{incident_id}

Partially update an incident's fields.

Only the fields provided in the request body are applied. Fields omitted (or explicitly set to null) are left unchanged.

  • Changing status to resolved automatically sets resolved_at if not already set.
  • Changing status away from resolved clears resolved_at and resets is_resolved to False.

Returns 404 if the incident does not exist within this org. Returns 422 if an invalid status or severity value is supplied.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for patching an incident's fields.

Response Body

application/json

application/json

curl -X PATCH "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
null
GET/api/v1/me/incidents/{incident_id}/related-issues

Issues on this incident's service with an overlapping activity window (#838) — see app/services/issue_incident_correlation.py for the relation rule. No console surface reads this yet (incident detail is M11 scope); it exists so that surface has a finished read to consume when it lands.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/related-issues"
{  "available": true,  "items": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "title": "string",      "status": "string",      "service_id": "641e839f-864e-4cce-98f9-40f6cbb3e9e0",      "first_seen_at": "2019-08-24T14:15:22Z",      "last_seen_at": "2019-08-24T14:15:22Z",      "total_count": 0    }  ],  "total": 0}

Get Incident Escalation

GET/api/v1/me/incidents/{incident_id}/escalation

The live escalation chain for this incident.

escalation_states is written by EscalationChainWorkflow's activities (#725) and was read by nothing until this endpoint: #725 built the state, #726 built acknowledge/resolve, and #732 (the console incident detail view) is console-only, so the read path fell between all three. Its acceptance criteria — which level is active, who was tried at which level, who acknowledged, and what happens next — are not answerable without it.

404 when the incident has no escalation: an incident whose org has no policy, or one created before the chain existed, is a normal state and not an error the console should render as a failure.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/escalation"
{  "incident_id": "2f811c5b-b888-4fb3-aac5-3c6a4b05df32",  "escalation_policy_id": "b590ec5a-9a9d-41d4-a03a-f2dca587b539",  "policy_name": "string",  "status": "string",  "current_level": 0,  "level_started_at": "2019-08-24T14:15:22Z",  "level_advances_at": "2019-08-24T14:15:22Z",  "notified_levels": [],  "acknowledged_at": "2019-08-24T14:15:22Z",  "acknowledged_by": "string",  "resolved_at": "2019-08-24T14:15:22Z",  "total_levels": 0,  "repeat_after_minutes": 0}

Update Incident Status

PATCH/api/v1/me/incidents/{incident_id}/status

Update incident status with state machine validation.

Body: {"status": "identified", "message": "optional update message"}

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X PATCH "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/status" \  -H "Content-Type: application/json" \  -d '{}'
null

Acknowledge Incident

POST/api/v1/me/incidents/{incident_id}/acknowledge

Acknowledge an incident.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/acknowledge" \  -H "Content-Type: application/json" \  -d '{}'
null

Create Incident Manual

POST/api/v1/me/incidents/

Manually create an incident for an organization.

Useful for planned maintenance, external outages, or any incident not automatically detected by the monitoring engine.

If monitor_id is provided the monitor must belong to this organization, otherwise 404 is returned.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for manually creating an incident.

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/me/incidents/" \  -H "Content-Type: application/json" \  -d '{    "title": "string"  }'
null

List Incident Updates

GET/api/v1/me/incidents/{incident_id}/updates

Return all timeline updates for an incident, ordered oldest-first.

Returns 404 if the incident does not exist within this org.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/updates"
[  {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "incident_id": "2f811c5b-b888-4fb3-aac5-3c6a4b05df32",    "message": "string",    "created_by": "string",    "created_at": "2019-08-24T14:15:22Z"  }]

Create Incident Update

POST/api/v1/me/incidents/{incident_id}/updates

Post a timeline update on an incident.

The calling user must have editor role or above. Returns 404 if the incident does not exist within this org.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for posting a timeline update on an incident.

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/updates" \  -H "Content-Type: application/json" \  -d '{    "message": "string"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "incident_id": "2f811c5b-b888-4fb3-aac5-3c6a4b05df32",  "message": "string",  "created_by": "string",  "created_at": "2019-08-24T14:15:22Z"}

Get Incident Timeline

GET/api/v1/me/incidents/{incident_id}/timeline

The incident timeline: status updates and comments interleaved, oldest-first (#589, epic collaboration-foundation; COLLAB §5.3 — docs/v2/architecture/COLLABORATION_ARCHITECTURE.md; the comment update type 05-incidents/api.md:298 already advertises).

Comments are read from the comments table (app/services/comment_service.py), not written into incident_updates — this endpoint is a view over both tables, not a second store for the same text. Pagination and the type/from/to query filters 05-incidents/api.md's fuller contract describes are not built here; nothing in #589's acceptance criteria calls for them, and adding them speculatively is exactly what CLAUDE.md's "Simplicity First" asks not to do.

Returns 404 if the incident does not exist within this org.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Response Body

application/json

application/json

curl -X GET "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/timeline"
{}

Resolve Incident

POST/api/v1/me/incidents/{incident_id}/resolve

Resolve an open incident for the organization.

Returns 400 if the incident is already resolved. Returns 404 if the incident does not exist within this org.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for resolving an incident.

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/resolve" \  -H "Content-Type: application/json" \  -d '{}'
null

Assign Incident

POST/api/v1/me/incidents/{incident_id}/assign

Assign an incident to a user or a team (COLLAB §4 — shared assignment mechanism, #588).

Returns 400 if assignee_id does not resolve to a live user or team in this organization (the service-layer check that stands in for the foreign key assignee_id cannot carry, since it points at two tables). Returns 404 if the incident does not exist within this org.

Assignment is not authorization: this endpoint requires editor role or above to perform the assignment, same as before, but being assigned grants the assignee nothing beyond whatever role they already hold.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Request body for assigning an incident to a user or a team (COLLAB §4.1 — docs/v2/architecture/COLLABORATION_ARCHITECTURE.md). assignee_id is validated against assignee_type in the org by the shared app/services/assignment_service.py::validate_assignee helper — no foreign key is possible on a column that points at two tables.

Response Body

application/json

application/json

curl -X POST "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/assign" \  -H "Content-Type: application/json" \  -d '{    "assignee_type": "user",    "assignee_id": "e209ca2d-190b-4818-b659-67d4ef4f1ce8"  }'
null

Unassign Incident

DELETE/api/v1/me/incidents/{incident_id}/assign

Remove the assignee from an incident.

Idempotent — returns 200 even if the incident was already unassigned. Returns 404 if the incident does not exist within this org.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Path Parameters

incident_id*Incident Id
Formatuuid

Response Body

application/json

application/json

curl -X DELETE "https://example.com/api/v1/me/incidents/497f6eca-6276-4993-bfeb-53cbbbba6f08/assign"
null

Heartbeat

Previous Page

Ingestion tokens

Next Page