> For the complete documentation index, see [llms.txt](https://docs.nerovasystems.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nerovasystems.com/guides/observe-and-account/incidents.md).

# Monitor incidents

Incidents report operational problems affecting a tenant's employee. Today they cover channel problems, such as a WhatsApp connection that needs reauthorization. This guide builds the status banner and the routing that gets the right person fixing the problem.

> **Experimental.** The `/api/v1/**` operations on this page are callable with your Live key (`nrv_live_`), which runs on the free testing allowance until a commercial agreement is signed or a card is saved. See [Lifecycle and availability](https://docs.nerovasystems.com/documentation/api/lifecycle).

## What you'll build

A polled health check per tenant: a banner when something is wrong, a merchant call to action when the fix is theirs, and a quiet screen when everything works.

## Prerequisites

* An activated tenant and an API key with `incident:read`; see [Authentication](https://docs.nerovasystems.com/documentation/getting-started/authentication).

## 1. Poll for active incidents

```bash
curl --request GET \
  --url "https://api.nerovasystems.com/api/v1/tenants/{tenantId}/incidents?Status=active" \
  --header "Accept: application/json" \
  --header "Authorization: ******"
```

Results are cursor-paginated (`Limit` 1–100, default 50); `Status` filters on `active`, `recovering`, or `resolved`, and `From`/`To` bound the window to at most 31 days. Incident identifiers are stable and descriptive, for example `incident_whatsapp_reauthorization`, `incident_whatsapp_registration`, and `incident_whatsapp_not_connected`. A tenant whose employee is not configured returns `"availability": "unavailable"` with an empty list; treat that as "nothing to monitor yet", not as healthy.

## 2. Route by recovery status

`recoveryStatus` tells you who acts:

* `merchant_action_required`: the merchant must do something, for example reauthorize the WhatsApp connection. Show the incident `summary` and send them to the fix; if you embed Nerova surfaces, deep-link the right screen via [Host UI integration](https://docs.nerovasystems.com/documentation/platform/host-ui-integration).
* `monitoring`: Nerova is watching recovery. Show a "recovering" state and keep polling; no merchant action helps here.

`severity` (for example `high` or `medium`) drives how loudly you surface it, and `hostReference` names the affected resource, typically the channel.

## 3. Clear the banner

An incident moves through `active`, `recovering`, and `resolved`. Keep the banner until the item you showed reports `resolved` (poll with `Status=resolved` or without a filter to see it flip), then drop it. The channel model behind most incidents is described in [Channels and routing](https://docs.nerovasystems.com/documentation/concepts/channels).

## Next steps

* Persisted attention items needing a human answer, rather than a broken channel: [Work the attention queue](https://github.com/Nerova-Systems/Project-Songbird/tree/main/docs/guides/attention.md).
* Hear about capability suspensions without polling: [Receive events with webhooks](/guides/build-well/webhooks.md).
* Full request and response shapes: [Incidents reference](https://docs.nerovasystems.com/api-reference/incidents).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nerovasystems.com/guides/observe-and-account/incidents.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.