# Incidents Incidents: open, update and resolve them. **Common tasks** - [List incidents](#get-organizations-organization-incidents) - [Post an update](#post-organizations-organization-incidents-incident-updates) - [Acknowledge an incident](#post-organizations-organization-incidents-incident-acknowledge) **Only in the app:** Nothing. Monitors open incidents; a token can update, annotate and acknowledge them, as the app can. **How it works in the app:** [help article](https://infranest.io/docs/incidents). **Scopes:** Read with `monitoring.read`, change with `monitoring.write`. See [Tokens and scopes](../tokens-and-scopes.md#scopes).
[Incidents](#incidents) 7
Every endpoint below takes a token in the `Authorization: Bearer` header and answers JSON. Errors use the shared format in [Errors](../errors.md). Base address: `https://api.infranest.io/api`. ## Incidents ### List incidents {#get-organizations-organization-incidents}
`GET` `/organizations/{organization}/incidents` **Scope:** `monitoring.read` · **Changes data:** no A paginated list of your monitors’ incidents with their monitor, status, impact, latest update and who acknowledged each one, plus counts in `meta`. `period` is `24h`, `7d` (default), `30d` or `all`; filter with `status` (`open`, `acked` or `resolved`) and `search`, or pass `incident` to fetch a single incident whatever its age. | Field | Type | Notes | |---|---|---| | `organization_id`
path · required | integer | Your organization's ID. | **Errors:** [`unauthenticated`](../errors.md#unauthenticated), [`scope_missing`](../errors.md#scope_missing), [`wrong_organization`](../errors.md#wrong_organization), [`test_token_required`](../errors.md#test_token_required), [`test_token_sandbox_only`](../errors.md#test_token_sandbox_only), [`permission_denied`](../errors.md#permission_denied), [`not_found`](../errors.md#not_found), [`rate_limited`](../errors.md#rate_limited)
**Request** ```sh curl "https://api.infranest.io/api/organizations/42/incidents" \ -H "Authorization: Bearer $INFRANEST_TOKEN" \ -H "Accept: application/json" ``` **Response** · 200 ```json { "current_page": 1, "data": [ { "id": 2, "monitoring_check_id": 1, "source": "monitor", "title": "Brief marketing-site blip", "status": "resolved", "impact": "minor", "started_at": "2026-01-09T11:45:00.000000Z", "resolved_at": "2026-01-09T12:00:00.000000Z", "duration_seconds": 900, "cause": null, "description": null, "external_status": null, "external_url": null, "is_planned": false, "acknowledged_at": null, "acknowledged_by": null, "check": { "id": 1, "name": "Marketing site", "type": "http", "last_status": "up", "interval_minutes": 0 }, "updates": [ { "id": 5, "monitoring_incident_id": 2, "status": "resolved", "message": "A CDN configuration change was rolled back and the site recovered. No other services were affected.", "user_id": null, "created_at": "2026-01-09T12:00:00.000000Z", "user": null } ] }, { "id": 1, "monitoring_check_id": 4, "source": "monitor", "title": "Checkout returning 503", "status": "investigating", "impact": "major", "started_at": "2026-01-15T11:20:00.000000Z", "resolved_at": null, "duration_seconds": null, "cause": "Upstream payment gateway timeout", "description": null, "external_status": null, "external_url": null, "is_planned": false, "acknowledged_at": null, "acknowledged_by": null, "check": { "id": 4, "name": "Checkout flow", "type": "http", "last_status": "down", "interval_minutes": 0 }, "updates": [ { "id": 3, "monitoring_incident_id": 1, "status": "monitoring", "message": "The failover is live and checkout is succeeding again. Watching error rates before we call this resolved.", "user_id": null, "created_at": "2026-01-15T11:54:00.000000Z", "user": null } ] } ], "first_page_url": "http://localhost/api/organizations/1/incidents?page=1", "from": 1, "last_page": 1, "last_page_url": "http://localhost/api/organizations/1/incidents?page=1", "links": [ { "url": null, "label": "« Previous", "page": null, "active": false }, { "url": "http://localhost/api/organizations/1/incidents?page=1", "label": "1", "page": 1, "active": true } ], "next_page_url": null, "path": "http://localhost/api/organizations/1/incidents", "per_page": 25, "prev_page_url": null, "to": 2, "total": 2, "meta": { "counts": { "total": 2, "open": 1, "acked": 0, "resolved": 1 } } } ```
--- ### Update an incident {#patch-organizations-organization-incidents-incident}
`PATCH` `/organizations/{organization}/incidents/{incident}` **Scope:** `monitoring.write` · **Changes data:** yes — only where API writes are switched on for the organization Changes an incident’s `title`, `status`, `impact`, `description` or `is_planned`. Setting `status` to `resolved` resolves an open incident, and any other status reopens a resolved one; incidents imported from a third-party status page cannot be edited. | Field | Type | Notes | |---|---|---| | `organization_id`
path · required | integer | Your organization's ID. | | `incident_id`
path · required | integer | The incident's ID. | | `title`
body | string, nullable | Must not be greater than 255 characters. | | `status`
body | string | One of: `investigating`, `identified`, `monitoring`, `resolved`. | | `impact`
body | string | One of: `critical`, `major`, `minor`, `none`. | | `description`
body | string, nullable | Must not be greater than 5000 characters. | | `is_planned`
body | boolean | | **Errors:** [`unauthenticated`](../errors.md#unauthenticated), [`scope_missing`](../errors.md#scope_missing), [`wrong_organization`](../errors.md#wrong_organization), [`test_token_required`](../errors.md#test_token_required), [`test_token_sandbox_only`](../errors.md#test_token_sandbox_only), [`permission_denied`](../errors.md#permission_denied), [`write_disabled`](../errors.md#write_disabled), [`organization_suspended`](../errors.md#organization_suspended), [`not_found`](../errors.md#not_found), [`validation_failed`](../errors.md#validation_failed), [`rate_limited`](../errors.md#rate_limited)
**Request** ```sh curl -X PATCH "https://api.infranest.io/api/organizations/42/incidents/1" \ -H "Authorization: Bearer $INFRANEST_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"status":"identified","impact":"major"}' ``` **Response** · 200 ```json { "id": 1, "monitoring_check_id": 4, "started_at": "2026-01-15T11:20:00.000000Z", "resolved_at": null, "duration_seconds": null, "cause": "Upstream payment gateway timeout", "affected_probe_ids": null, "acknowledged_at": null, "acknowledged_by": null, "created_at": "2026-01-15T12:00:00.000000Z", "updated_at": "2026-01-15T12:00:00.000000Z", "description": null, "is_planned": false, "title": "Checkout returning 503", "status": "identified", "impact": "major", "source": "monitor", "server_id": null, "cloud_server_alert_rule_id": null, "external_status": null, "external_url": null, "alert_rule_state_id": null, "folded_into": null, "unstable_at": null, "unstable_ended_at": null, "outage_count": 1, "down_since": null, "downtime_seconds": 0, "outages": null, "acknowledged_by_name": null } ```
--- ### Acknowledge an incident {#post-organizations-organization-incidents-incident-acknowledge}
`POST` `/organizations/{organization}/incidents/{incident}/acknowledge` **Scope:** `monitoring.write` · **Changes data:** yes — only where API writes are switched on for the organization Marks the incident as acknowledged by you, so your team knows someone is on it, and returns it with who acknowledged it. | Field | Type | Notes | |---|---|---| | `organization_id`
path · required | integer | Your organization's ID. | | `incident_id`
path · required | integer | The incident's ID. | **Errors:** [`unauthenticated`](../errors.md#unauthenticated), [`scope_missing`](../errors.md#scope_missing), [`wrong_organization`](../errors.md#wrong_organization), [`test_token_required`](../errors.md#test_token_required), [`test_token_sandbox_only`](../errors.md#test_token_sandbox_only), [`permission_denied`](../errors.md#permission_denied), [`write_disabled`](../errors.md#write_disabled), [`organization_suspended`](../errors.md#organization_suspended), [`not_found`](../errors.md#not_found), [`idempotency_in_progress`](../errors.md#idempotency_in_progress), [`validation_failed`](../errors.md#validation_failed), [`idempotency_key_reused`](../errors.md#idempotency_key_reused), [`rate_limited`](../errors.md#rate_limited)
**Request** ```sh curl -X POST "https://api.infranest.io/api/organizations/42/incidents/1/acknowledge" \ -H "Authorization: Bearer $INFRANEST_TOKEN" \ -H "Accept: application/json" ``` **Response** · 200 ```json { "id": 1, "monitoring_check_id": 4, "started_at": "2026-01-15T11:20:00.000000Z", "resolved_at": null, "duration_seconds": null, "cause": "Upstream payment gateway timeout", "affected_probe_ids": null, "acknowledged_at": "2026-01-15T12:00:00.000000Z", "acknowledged_by": { "id": 1, "first_name": null, "last_name": null, "analytics_id": null }, "created_at": "2026-01-15T12:00:00.000000Z", "updated_at": "2026-01-15T12:00:00.000000Z", "description": null, "is_planned": false, "title": "Checkout returning 503", "status": "investigating", "impact": "major", "source": "monitor", "server_id": null, "cloud_server_alert_rule_id": null, "external_status": null, "external_url": null, "alert_rule_state_id": null, "folded_into": null, "unstable_at": null, "unstable_ended_at": null, "outage_count": 1, "down_since": null, "downtime_seconds": 0, "outages": null, "acknowledged_by_name": null, "check": { "id": 4, "organization_id": 1, "name": "Checkout flow", "type": "http", "target": "https://northwind.com/checkout", "enabled": true, "settings": [], "last_status": "down", "last_checked_at": "2026-01-15T11:58:00.000000Z", "deleted_at": null, "created_at": "2026-01-15T12:00:00.000000Z", "updated_at": "2026-01-15T12:00:00.000000Z", "last_message": "HTTP 503 — Service Unavailable", "consecutive_failures": 8, "flap_threshold": 2, "last_status_changed_at": "2026-01-15T11:20:00.000000Z", "consensus_threshold": 1, "preferred_regions": [ "EU" ], "probe_mode": "any", "ip_version": "prefer_ipv4", "slow_response_ms": null, "ssl_check_enabled": true, "ssl_expiry_days": 21, "heartbeat_uuid": null, "last_ping_at": null, "silenced_until": null, "silenced_by": null, "is_suppressed_by_parent": false, "external_service_id": null, "external_component_ids": null, "external_alerts_enabled": false, "region_checked_at": null, "region_consensus_threshold": null, "last_reason_code": null, "last_reason_params": null, "interval_seconds": 300, "badge_enabled": false, "badge_token": null, "purge_after": null, "purge_reminder_sent_at": null, "deleted_by_id": null, "deleted_by_label": null, "deletion_reason": null, "server_id": null, "server_link": null, "pagerduty_down_severity": "critical", "pagerduty_degraded_severity": "warning", "interval_minutes": 5 } } ```
--- ### Add a team note to an incident {#post-organizations-organization-incidents-incident-notes}
`POST` `/organizations/{organization}/incidents/{incident}/notes` **Scope:** `monitoring.write` · **Changes data:** yes — only where API writes are switched on for the organization Adds an internal note in `body` for your team. Notes never appear on a status page. | Field | Type | Notes | |---|---|---| | `organization_id`
path · required | integer | Your organization's ID. | | `incident_id`
path · required | integer | The incident's ID. | | `body`
body · required | string | | **Errors:** [`unauthenticated`](../errors.md#unauthenticated), [`scope_missing`](../errors.md#scope_missing), [`wrong_organization`](../errors.md#wrong_organization), [`test_token_required`](../errors.md#test_token_required), [`test_token_sandbox_only`](../errors.md#test_token_sandbox_only), [`permission_denied`](../errors.md#permission_denied), [`write_disabled`](../errors.md#write_disabled), [`organization_suspended`](../errors.md#organization_suspended), [`not_found`](../errors.md#not_found), [`idempotency_in_progress`](../errors.md#idempotency_in_progress), [`validation_failed`](../errors.md#validation_failed), [`idempotency_key_reused`](../errors.md#idempotency_key_reused), [`rate_limited`](../errors.md#rate_limited)
**Request** ```sh curl -X POST "https://api.infranest.io/api/organizations/42/incidents/1/notes" \ -H "Authorization: Bearer $INFRANEST_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"body":"Rolled back release 2026.01.15 — error rate back to normal."}' ``` **Response** · 201 — Created ```json { "id": 1, "body": "Rolled back release 2026.01.15 — error rate back to normal.", "via": "app", "by": "Alex Rivera", "created_at": "2026-01-15T12:00:00+00:00" } ```
--- ### Remove an incident acknowledgement {#post-organizations-organization-incidents-incident-unacknowledge}
`POST` `/organizations/{organization}/incidents/{incident}/unacknowledge` **Scope:** `monitoring.write` · **Changes data:** yes — only where API writes are switched on for the organization Clears the acknowledgement so the incident reads as unhandled again. | Field | Type | Notes | |---|---|---| | `organization_id`
path · required | integer | Your organization's ID. | | `incident_id`
path · required | integer | The incident's ID. | **Errors:** [`unauthenticated`](../errors.md#unauthenticated), [`scope_missing`](../errors.md#scope_missing), [`wrong_organization`](../errors.md#wrong_organization), [`test_token_required`](../errors.md#test_token_required), [`test_token_sandbox_only`](../errors.md#test_token_sandbox_only), [`permission_denied`](../errors.md#permission_denied), [`write_disabled`](../errors.md#write_disabled), [`organization_suspended`](../errors.md#organization_suspended), [`not_found`](../errors.md#not_found), [`idempotency_in_progress`](../errors.md#idempotency_in_progress), [`validation_failed`](../errors.md#validation_failed), [`idempotency_key_reused`](../errors.md#idempotency_key_reused), [`rate_limited`](../errors.md#rate_limited)
**Request** ```sh curl -X POST "https://api.infranest.io/api/organizations/42/incidents/1/unacknowledge" \ -H "Authorization: Bearer $INFRANEST_TOKEN" \ -H "Accept: application/json" ``` **Response** · 200 ```json { "id": 1, "monitoring_check_id": 4, "started_at": "2026-01-15T11:20:00.000000Z", "resolved_at": null, "duration_seconds": null, "cause": "Upstream payment gateway timeout", "affected_probe_ids": null, "acknowledged_at": null, "acknowledged_by": null, "created_at": "2026-01-15T12:00:00.000000Z", "updated_at": "2026-01-15T12:00:00.000000Z", "description": null, "is_planned": false, "title": "Checkout returning 503", "status": "investigating", "impact": "major", "source": "monitor", "server_id": null, "cloud_server_alert_rule_id": null, "external_status": null, "external_url": null, "alert_rule_state_id": null, "folded_into": null, "unstable_at": null, "unstable_ended_at": null, "outage_count": 1, "down_since": null, "downtime_seconds": 0, "outages": null, "acknowledged_by_name": null } ```
--- ### Get an incident’s timeline {#get-organizations-organization-incidents-incident-updates}
`GET` `/organizations/{organization}/incidents/{incident}/updates` **Scope:** `monitoring.read` · **Changes data:** no The incident’s public status updates and internal team notes, plus the alert channels that were notified, deploys shortly before it began, who PagerDuty is paging, notes from PagerDuty and tickets opened for it. | Field | Type | Notes | |---|---|---| | `organization_id`
path · required | integer | Your organization's ID. | | `incident_id`
path · required | integer | The incident's ID. | **Errors:** [`unauthenticated`](../errors.md#unauthenticated), [`scope_missing`](../errors.md#scope_missing), [`wrong_organization`](../errors.md#wrong_organization), [`test_token_required`](../errors.md#test_token_required), [`test_token_sandbox_only`](../errors.md#test_token_sandbox_only), [`permission_denied`](../errors.md#permission_denied), [`not_found`](../errors.md#not_found), [`rate_limited`](../errors.md#rate_limited)
**Request** ```sh curl "https://api.infranest.io/api/organizations/42/incidents/1/updates" \ -H "Authorization: Bearer $INFRANEST_TOKEN" \ -H "Accept: application/json" ``` **Response** · 200 ```json { "updates": [ { "id": 3, "monitoring_incident_id": 1, "status": "monitoring", "message": "The failover is live and checkout is succeeding again. Watching error rates before we call this resolved.", "user_id": null, "created_at": "2026-01-15T11:54:00.000000Z", "user": null }, { "id": 8, "monitoring_incident_id": 1, "status": "investigating", "message": "The provider has acknowledged an incident on their side. We are holding while they work.", "user_id": 1, "created_at": "2026-01-15T11:51:00.000000Z", "user": { "id": 1, "first_name": null, "last_name": null, "analytics_id": null } } ], "team_notes": [], "notified": [ "email", "slack" ], "deploys": [ { "id": 9, "source": "github", "kind": "deployment", "workflow": null, "repository": "northwind-cloud/storefront", "environment": "production", "state": "success", "sha": "f19e6c7000000000000000000000000000000000", "ref": "main", "actor": "jordan-k", "url": "https://github.com/northwind-cloud/storefront/deployments", "deployed_at": "2026-01-15T11:17:00+00:00" } ], "oncall": [], "pagerduty_notes": [ { "id": 2, "author_name": "Alex Rivera", "content": "Secondary payment route is warmed up — Sam is switching checkout over to it now.", "created_at": "2026-01-15T11:45:00+00:00" }, { "id": 1, "author_name": "Sam Okoye", "content": "Payment gateway status page shows degraded API performance in eu-west. Opening a ticket with them.", "created_at": "2026-01-15T11:26:00+00:00" } ], "tickets": [] } ```
--- ### Post an incident update {#post-organizations-organization-incidents-incident-updates}
`POST` `/organizations/{organization}/incidents/{incident}/updates` **Scope:** `monitoring.write` · **Changes data:** yes — only where API writes are switched on for the organization Posts a public status update with a `status` and `message`, and moves the incident to that status (`resolved` resolves it). Status page subscribers are notified unless you send `notify_subscribers: false`; incidents imported from a third-party status page cannot be updated. | Field | Type | Notes | |---|---|---| | `organization_id`
path · required | integer | Your organization's ID. | | `incident_id`
path · required | integer | The incident's ID. | | `status`
body · required | string | One of: `investigating`, `identified`, `monitoring`, `resolved`. | | `message`
body · required | string | Must not be greater than 5000 characters. | | `notify_subscribers`
body | boolean | | **Errors:** [`unauthenticated`](../errors.md#unauthenticated), [`scope_missing`](../errors.md#scope_missing), [`wrong_organization`](../errors.md#wrong_organization), [`test_token_required`](../errors.md#test_token_required), [`test_token_sandbox_only`](../errors.md#test_token_sandbox_only), [`permission_denied`](../errors.md#permission_denied), [`write_disabled`](../errors.md#write_disabled), [`organization_suspended`](../errors.md#organization_suspended), [`not_found`](../errors.md#not_found), [`idempotency_in_progress`](../errors.md#idempotency_in_progress), [`validation_failed`](../errors.md#validation_failed), [`idempotency_key_reused`](../errors.md#idempotency_key_reused), [`rate_limited`](../errors.md#rate_limited)
**Request** ```sh curl -X POST "https://api.infranest.io/api/organizations/42/incidents/1/updates" \ -H "Authorization: Bearer $INFRANEST_TOKEN" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"status":"monitoring","message":"A fix is out; we are watching checkout recover."}' ``` **Response** · 201 — Created ```json { "monitoring_incident_id": 1, "status": "monitoring", "message": "A fix is out; we are watching checkout recover.", "user_id": 1, "created_at": "2026-01-15T12:00:00.000000Z", "id": 9, "incident": { "id": 1, "monitoring_check_id": 4, "started_at": "2026-01-15T11:20:00.000000Z", "resolved_at": null, "duration_seconds": null, "cause": "Upstream payment gateway timeout", "affected_probe_ids": null, "acknowledged_at": null, "acknowledged_by": null, "created_at": "2026-01-15T12:00:00.000000Z", "updated_at": "2026-01-15T12:00:00.000000Z", "description": null, "is_planned": false, "title": "Checkout returning 503", "status": "investigating", "impact": "major", "source": "monitor", "server_id": null, "cloud_server_alert_rule_id": null, "external_status": null, "external_url": null, "alert_rule_state_id": null, "folded_into": null, "unstable_at": null, "unstable_ended_at": null, "outage_count": 1, "down_since": null, "downtime_seconds": 0, "outages": null, "acknowledged_by_name": null }, "user": { "id": 1, "first_name": null, "last_name": null, "analytics_id": null } } ```