📘

Use the hub_url received in the registration response as your base URL.

📘

This API requires the device to authenticate, see Device Authentication.

Open a custom incident on the device that are not covered by telemetry Incident Rules. This API allows the device to open custom incidents based on detected errors or internal state.

The device should call the Close Incident API to close the incident once the issue was resolved.

Reporting incidents that happened while the device was offline

If the device (or its gateway) lost connectivity, it can cache faults and report them once it reconnects. Send the time the fault actually started in timestamp, and Xyte uses it as the incident's start time in the portals, the API, webhooks and ticketing integrations.

If the fault has already been resolved, also send closed_at. The incident is then created already closed, in a single call, with no need to call the Close Incident API.

Replace the example times with times from the last 7 days.

{
	"issue": "amp_overheat",
	"priority": 2,
	"title": "Amplifier overheated",
	"timestamp": "2026-10-05T09:12:00Z",
	"closed_at": "2026-10-06T07:40:00Z"
}

Rules:

• timestamp and closed_at are ISO-8601 datetimes with a full date, time with seconds and a zone offset (for example 2026-10-05T09:12:00Z or 2026-10-05T11:12:00+02:00). Date-only values, times without a zone or without seconds, and epoch numbers are rejected with 422 ("timestamp must be an ISO-8601 datetime with offset").
• timestamp must be within the last 7 days. closed_at must be between timestamp and now. These windows apply to new reports only; a retry of an accepted report is matched first (see below).
• Both timestamp and closed_at may be up to 2 minutes in the future (device clock drift); such a value is stored as the current time. Anything further in the future is rejected.
• issue is required whenever timestamp is sent.
• closed_at requires timestamp.
• Invalid values return 422 with an error message.

🚧

Behaviour change for devices already sending these fields

Before this feature, timestamp and closed_at were ignored and the incident was opened at the time of the call. They are now validated: a request carrying either field with a value outside the rules above (wrong format, older than 7 days, timestamp without issue) returns 422 instead of opening the incident. If your device already sends either field, make sure it follows these rules, or stop sending it.

Behaviour:

• Retries are safe. Sending the same issue and timestamp again returns the existing incident instead of creating a duplicate. The retry is matched before the 7-day and 2-minute checks, so it still returns the original incident after the window has passed. Other fields on a repeat (title, priority, description) are ignored - the original incident is returned unchanged. If the retry carries a closed_at and the incident is not closed yet, the incident is closed at that time, and connected integrations are notified of the close.
• Newer incident of the same issue. If the device already has a newer incident (open or closed) with the same issue, the reported incident is still recorded and is closed when the newer one started - unless the closed_at you sent is earlier, in which case that time is used.
• Older incident of the same issue still open at timestamp. If an incident with the same issue started before timestamp and is still open - or was closed only after timestamp - the request returns the same 403 a request without timestamp returns.
• Notifications. An incident created already closed (by closed_at, or because a newer incident of the same issue exists) is recorded in the incident history only. It does not open tickets, call webhooks or send notifications. A reported incident that is still open notifies as usual; if the customer has configured a notification delay on the device's space, it counts from timestamp, so a fault older than the delay notifies at once.

Return Data

{
	"incident_id": "3dce7586-7c40-4392-affb-f728f20bb350"
}

Notes

Incident generation will only work for claimed devices. Calling the API for unclaimed device will return successfully with a dummy incident_id.