TL;DR
- An incident is a known disruption published by clever-PV, e.g. a vendor cloud outage or a problem with specific device models. Use it to tell users "this is a known issue" instead of letting them debug their own setup.
GET /v1/users/{userId}/incidents?audience=user|appreturns a feed of incidents. It is the only place where app-wide incidents (not tied to a vendor) appear.- Device responses carry incidents for the device's vendor/model in
model.incidents[]. Vendor responses (user-scoped and public catalog) carry them inincidents[]. - Visibility: active incidents are always returned. Closed incidents stay visible for 30 days after
endsAtUtc. content.title/content.textare localized.x-cpv-languagetakes precedence overAccept-Language. Without a header, or for an unsupported language, you get English.
Incident object
Code
| Field | Type | Notes |
|---|---|---|
id | uuid | Stable incident id. Use it to de-duplicate an incident that shows up on several devices or vendors. |
vendorId | uuid | null | Affected vendor. null for scope: app and scope: deviceTypes. |
vendorName | string | null | Display name of the affected vendor. null for scope: app and scope: deviceTypes. |
scope | string | vendor (all models of the vendor), models (only the listed models of the vendor), app (app-wide, not tied to a vendor or device), deviceTypes (devices of older integrations that are not part of the vendor catalog). New values may be added; treat unknown values like deviceTypes. |
modelIds | uuid[] | Affected model ids, limited to the models in the context of the response (see Where incidents appear). Empty for vendor, app and deviceTypes, and can be empty for a models incident that matches a device of an older integration. |
state | string | active or closed. |
severity | string | info, warning or critical. |
content | object | title and text in the resolved language (see Language). |
createdAtUtc | UTC timestamp | When the incident was created. |
startsAtUtc | UTC timestamp | When the disruption started. It can lie in the future for an announced incident. |
endsAtUtc | UTC timestamp | null | When the disruption ended. Set only when state is closed, null while active. |
updatedAtUtc | UTC timestamp | Last change to the incident (e.g. new text or state change). |
appId | string | null | Set only on scope: app incidents in the feed and contains your app's identifier. null otherwise. |
Timestamps are UTC in the form yyyy-MM-ddTHH:mm:ssZ. Enum values are camelCase strings, like everywhere else in the Connect API. Lists are sorted by startsAtUtc, newest first.
Visibility
| State | Returned? |
|---|---|
active | Always, regardless of startsAtUtc. |
closed | While endsAtUtc is at most 30 days in the past. After that the incident disappears from all responses. |
Incident feed
Code
Uses the same authentication and userId handling as all other /v1/users/{userId}/… endpoints (see Users and Homes).
audience (query, required):
| Value | Returns |
|---|---|
user | Incidents that affect the devices of this user's home, plus the app-wide incidents of your app. A user without devices only gets the app-wide incidents. |
app | Incidents for every vendor and model in your app's catalog (regardless of the user's devices), every incident that covers older integrations (e.g. scope: deviceTypes), and the app-wide incidents of your app. Use it for a general "known issues" view. |
Response: a wrapper with data[] holding incident objects. The feed is not paginated: all matching incidents are returned in one response, and cursor/size/total/hasMoreResults are not included.
Code
| Status | When |
|---|---|
200 | Feed returned. It can be empty. |
400 | audience is missing or not user / app. |
401 | Missing or invalid bearer token. |
403 | Token lacks the connect_api scope. For whitelabel apps also connectApiNotEnabledForApp (see Users and Homes). |
404 | Unknown userId of a whitelabel app (clientExternalUserNotFound, see Users and Homes). Otherwise check errorCode / detail. |
Where incidents appear
| Response | Field | Contains |
|---|---|---|
GET /v1/users/{userId}/devices, GET /v1/users/{userId}/devices/{deviceId} | model.incidents[] of each device | Incidents with scope: vendor for the device's vendor, with scope: models that include the device's model, and incidents that cover the device's older integration (e.g. scope: deviceTypes). modelIds holds at most the device's own model id. |
GET /v1/users/{userId}/vendors, GET /v1/users/{userId}/vendors/{vendorId} | incidents[] of each vendor | Incidents with scope: vendor for that vendor and with scope: models that include at least one of the vendor's listed models. modelIds is limited to the listed models. If you filter by category, only models of that category are matched. |
GET /v1/catalog/vendors, GET /v1/catalog/vendors/{vendorId} (Public Vendor Catalog) | incidents[] of each vendor | Same rules as the user-scoped vendor endpoints, applied to the catalog that is returned (your app's catalog or the default clever-PV catalog). Also returned to anonymous callers. |
GET /v1/users/{userId}/incidents | data[] | Vendor and model incidents as described in Incident feed, plus app-wide incidents. |
- App-wide incidents (
scope: app) only appear in the feed. Device and vendor responses never contain them. - The same incident can appear on several devices or vendors, and in the feed. De-duplicate by
id. POST /v1/users/{userId}/devicesreturns the created device with an emptymodel.incidents[]. Re-read the device to get its incidents.
Language
All endpoints above resolve content the same way:
- If the
x-cpv-languageheader is set, its value is used. It takes precedence overAccept-Language. - Otherwise the first entry of
Accept-Languageis used. Quality values (;q=) and further entries are ignored, soAccept-Language: fr-CH, de;q=0.9selects French. - Regional tags are reduced to their base language (
de-AT→de). - If that language is supported, the incident is returned in it. Otherwise English is returned, and German as a last resort. Without either header, English is returned.
Supported languages: de, en, nl, fr, it, es, pt, el, fi, sv, hr, sk, sl, et, lv, lt, bg.
Last modified on