Skip to content
NebulaCtrlInstall

Reference

View as Markdown

Status incidents API

6 operations. Every call needs a session cookie or an Authorization: Bearer nct_… token unless marked Public. Conventions, errors and scopes

GET/status-incidents

List status incidents

Incidents written by people and posted to status pages, newest first, with their timelines.

ParameterInTypeDescription
statusqueryenum: active | investigating | identified | monitoring | resolvedOnly incidents in this status; active = not resolved
pageIdquerystring (uuid)Only incidents posted to this status page
cursorquerystringOpaque cursor from a previous page's nextCursor
limitqueryinteger (int64)Page size (default 50, max 200)
Response 200 · OK · application/json
PageStatusIncidentView
  • StatusIncidentView[] | nullrequired
  • nextCursorstring
    Present when more items exist
Errors
  • 400Bad Request
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/status-incidents

Open a status incident

Opens an incident whose first timeline entry is body and posts it to the pages. Its impact moves the pages' overall state while it is not resolved. Requires the admin scope.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
Request body · application/json · required
CreateIncidentInputBody
  • bodystringrequired
    The first update of the timeline. Plain text, line breaks kept
  • impactenum: none | minor | major | criticalrequired
    How the page's overall state changes while the incident is active: critical = major outage, major = partial outage, minor = degraded, none = nothing
  • pageIdsstring[] | null
    The status pages to post it to
  • serviceIdsstring[] | null
    The affected services
  • statusenum: investigating | identified | monitoring | resolved
    Default investigating
  • titlestringrequired
Response 201 · Created · application/json
StatusIncidentView
  • createdAtstring (date-time)required
  • idstringrequired
  • impactenum: none | minor | major | criticalrequired
  • pageIdsstring[] | nullrequired
    The status pages the incident is posted to
  • resolvedAtstring (date-time) | nullrequired
  • serviceIdsstring[] | nullrequired
    The services it affects (shown as the affected components of each page that has them)
  • statusenum: investigating | identified | monitoring | resolvedrequired
  • titlestringrequired
  • updatedAtstring (date-time)required
  • StatusIncidentUpdateView[] | nullrequired
    The timeline, newest first
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

GET/status-incidents/{incidentId}

Get a status incident

ParameterInTypeDescription
incidentIdrequiredpathstring
Response 200 · OK · application/json
StatusIncidentView
  • createdAtstring (date-time)required
  • idstringrequired
  • impactenum: none | minor | major | criticalrequired
  • pageIdsstring[] | nullrequired
    The status pages the incident is posted to
  • resolvedAtstring (date-time) | nullrequired
  • serviceIdsstring[] | nullrequired
    The services it affects (shown as the affected components of each page that has them)
  • statusenum: investigating | identified | monitoring | resolvedrequired
  • titlestringrequired
  • updatedAtstring (date-time)required
  • StatusIncidentUpdateView[] | nullrequired
    The timeline, newest first
Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

PATCH/status-incidents/{incidentId}

Update a status incident

Changes the title, impact, pages or services; omitted fields stay. The status and timeline change with POST /status-incidents/{incidentId}/updates. Requires the admin scope.

ParameterInTypeDescription
incidentIdrequiredpathstring
Request body · application/json · required
UpdateIncidentInputBody
  • impactenum: none | minor | major | critical
  • pageIdsstring[] | null
    Replaces the pages; [] withdraws the incident from every page
  • serviceIdsstring[] | null
    Replaces the affected services
  • titlestring
Response 200 · OK · application/json
StatusIncidentView
  • createdAtstring (date-time)required
  • idstringrequired
  • impactenum: none | minor | major | criticalrequired
  • pageIdsstring[] | nullrequired
    The status pages the incident is posted to
  • resolvedAtstring (date-time) | nullrequired
  • serviceIdsstring[] | nullrequired
    The services it affects (shown as the affected components of each page that has them)
  • statusenum: investigating | identified | monitoring | resolvedrequired
  • titlestringrequired
  • updatedAtstring (date-time)required
  • StatusIncidentUpdateView[] | nullrequired
    The timeline, newest first
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

DELETE/status-incidents/{incidentId}

Delete a status incident

Deletes the incident and its timeline; it disappears from the pages. Requires the admin scope.

ParameterInTypeDescription
incidentIdrequiredpathstring
Response 204 · No Content

No body.

Errors
  • 401Unauthorized
  • 403Forbidden
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.

POST/status-incidents/{incidentId}/updates

Post an incident update

Adds a timeline entry and moves the incident to its status. resolved sets resolvedAt and ends the incident's effect on the pages' overall state; a later update with another status reopens it. Requires the admin scope.

ParameterInTypeDescription
Idempotency-KeyheaderstringClient-chosen key (<=255 chars). A retry with the same key replays the original response for 24 hours.
incidentIdrequiredpathstring
Request body · application/json · required
PostIncidentUpdateInputBody
  • bodystringrequired
    Plain text, line breaks kept
  • statusenum: investigating | identified | monitoring | resolvedrequired
Response 201 · Created · application/json
StatusIncidentView
  • createdAtstring (date-time)required
  • idstringrequired
  • impactenum: none | minor | major | criticalrequired
  • pageIdsstring[] | nullrequired
    The status pages the incident is posted to
  • resolvedAtstring (date-time) | nullrequired
  • serviceIdsstring[] | nullrequired
    The services it affects (shown as the affected components of each page that has them)
  • statusenum: investigating | identified | monitoring | resolvedrequired
  • titlestringrequired
  • updatedAtstring (date-time)required
  • StatusIncidentUpdateView[] | nullrequired
    The timeline, newest first
Errors
  • 401Unauthorized
  • 403Forbidden
  • 404Not Found
  • 409Conflict
  • 422Unprocessable Entity
  • 500Internal Server Error

Errors are RFC 9457 application/problem+json with a stable code field.