> ## Documentation Index
> Fetch the complete documentation index at: https://docs.energy.nayax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API usage

The Incident Management API lets you read and manage your network's incidents programmatically — pull them into a dashboard, wire them into your own alerting, or automate triage. This page covers the essentials; the full endpoint reference is under [Incident Management API](/api/incident-management/incidents/bulk-change-incident-status).

All endpoints are served under:

```
https://api.lynkwell.com/incident-management/v1
```

## Authentication

Requests are authenticated with an OAuth2 bearer token, the same way as the rest of the Nayax Energy Core API. Obtain a token with your API client credentials (see [Getting Started](/api)), then send it in the `Authorization` header:

```bash theme={null}
curl --request GET \
  --url "https://api.lynkwell.com/incident-management/v1/incidents" \
  --header "Authorization: Bearer ACCESS_TOKEN"
```

Reads require the `read:incident` scope; writes require `write:incident`. If your client is missing a scope, the request is rejected. Contact Nayax Energy Core support if your API client needs incident access.

## Listing and filtering incidents

`GET /incidents` returns your network's incidents, newest-detected first. The response wraps the page in a `data` object:

```json theme={null}
{
  "data": {
    "items": [
      { "id": "INC_2026_a1b2c3", "status": "NEW", "alertType": "HARDWARE_FAULT", "detectedAt": "2026-09-01T14:22:05.000Z" }
    ],
    "hasMore": true
  }
}
```

Narrow the list with query parameters — combine as many as you need:

| Parameter             | Filters to                                                                             |
| --------------------- | -------------------------------------------------------------------------------------- |
| `status`              | A single status, e.g. `NEW`.                                                           |
| `slaState`            | SLA standing, e.g. `AT_RISK`, `BREACHED`.                                              |
| `alertType`           | Incident type, e.g. `HARDWARE_FAULT`.                                                  |
| `stationId`           | Incidents affecting one station.                                                       |
| `locationId`          | Incidents at one location.                                                             |
| `assigneeUserId`      | Incidents assigned to one Support Operator.                                            |
| `autoResolved`        | `true` for incidents the platform closed, `false` for those a Support Operator closed. |
| `slaBreached`         | `true` for incidents that have breached their deadline.                                |
| `includeMerged`       | `true` to include merged-away incidents (excluded by default).                         |
| `dateFrom` + `dateTo` | A detection-time range (ISO-8601, sent together).                                      |

For example, open incidents at one site that are at risk of breaching:

```bash theme={null}
curl --request GET \
  --url "https://api.lynkwell.com/incident-management/v1/incidents?status=INVESTIGATING&locationId=loc_123&slaState=AT_RISK" \
  --header "Authorization: Bearer ACCESS_TOKEN"
```

## Pagination

Incident lists use **keyset pagination**, not page numbers. Two parameters control it:

* `limit` — page size, 1–100, default 20.
* `startingAfter` — the **id of the last item** you have already seen. The next page starts after it.

You do not compute an offset. To walk every page, take the `id` of the last item in `items` and pass it as `startingAfter` on the next request, and keep going while `hasMore` is `true`.

First page:

```bash theme={null}
curl --request GET \
  --url "https://api.lynkwell.com/incident-management/v1/incidents?limit=20" \
  --header "Authorization: Bearer ACCESS_TOKEN"
```

Response (truncated):

```json theme={null}
{
  "data": {
    "items": [
      { "id": "INC_2026_a1b2c3", "...": "..." },
      { "id": "INC_2026_z9y8x7" }
    ],
    "hasMore": true
  }
}
```

The last item's id is `INC_2026_z9y8x7`, so the next page is:

```bash theme={null}
curl --request GET \
  --url "https://api.lynkwell.com/incident-management/v1/incidents?limit=20&startingAfter=INC_2026_z9y8x7" \
  --header "Authorization: Bearer ACCESS_TOKEN"
```

Stop when `hasMore` is `false`. If you pass a `startingAfter` that no longer exists, the request returns a `400` with code `INVALID_CURSOR`.

> The activity feed (`GET /incidents/{id}/feed`) also uses `startingAfter`, but there the cursor is the opaque `id` of the last feed entry rather than an incident id. The rule is the same — pass back the last item's `id` — you just do not treat it as an incident id.

## Reading one incident and its sub-resources

`GET /incidents/{id}` returns a single incident, with its location and network joined in. The incident carries a roster **count** (`affectedStationCount`), not the roster itself; the roster and the other detail live on sub-resources:

| Sub-resource                 | Endpoint                                 |
| ---------------------------- | ---------------------------------------- |
| Affected stations (roster)   | `GET /incidents/{id}/affected-stations`  |
| Consolidated activity feed   | `GET /incidents/{id}/feed`               |
| Status history               | `GET /incidents/{id}/history`            |
| Assignment history           | `GET /incidents/{id}/assignment-history` |
| Comments                     | `GET /incidents/{id}/comments`           |
| Notifications sent           | `GET /incidents/{id}/notifications`      |
| Fault occurrences            | `GET /incidents/{id}/fault-occurrences`  |
| Session and command timeline | `GET /incidents/{id}/timeline`           |

Most of these paginate exactly like the incident list — `limit` (default 20, max 100) and `startingAfter` set to the last item's `id`. The **feed** is the one exception: as noted above, it also uses `startingAfter`, but its cursor is the opaque `id` of the last feed entry rather than an incident id, and its default `limit` is 25.

## Making changes

The API also supports the full incident workflow — creating incidents, transitioning status, assigning, commenting, and merging, splitting, or linking. These require the `write:incident` scope, and most writes are attributed to the acting Support Operator via a user id in the request body — `changedByUserId` on most routes, `authorUserId` when adding a comment. See the reference for the exact field on each route. See the [Incident Management API](/api/incident-management/incidents/bulk-change-incident-status) reference for the request bodies and responses, and the concept guides for what each action does:

* [Statuses and lifecycle](/guides/incidents/statuses-and-lifecycle) for status transitions.
* [Merging, splitting, and linking](/guides/incidents/merging-splitting-and-linking) for merge, split, and link.
* [Comments and history](/guides/incidents/comments-and-history) for comments and attachments.