# Incidents
## GET /incidents
> Get incidents.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.5-r.3"},"tags":[{"name":"Incidents"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"Incident":{"type":"object","properties":{"id":{"type":"number"},"summary":{"type":"string"},"status":{"$ref":"#/components/schemas/IncidentStatus"},"message":{"type":"string"},"sendNotification":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"affectedServices":{"type":"array","items":{"type":"object","properties":{"impact":{"$ref":"#/components/schemas/ServiceStatus"},"service":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}},"resolvedOn":{"type":"string","format":"date-time","readOnly":true},"subscribed":{"type":"boolean","readOnly":true},"affectedTeams":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/TeamRel"}}}},"IncidentStatus":{"type":"string","description":"the incident status","enum":["INVESTIGATING","IDENTIFIED","MONITORING","RESOLVED"]},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}}}},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}}}},"paths":{"/incidents":{"get":{"tags":["Incidents"],"summary":"Get incidents.","parameters":[{"name":"start-index","in":"query","description":"an integer specifying the starting point (beginning with 0) when paging through a list of entities","schema":{"type":"integer","format":"int32","default":0}},{"name":"max-results","in":"query","description":"the maximum number of results when paging through a list of incidents. (Note: when using ?include maximum is reduced to 25)","schema":{"maximum":100,"type":"integer","format":"int32","default":10}},{"name":"include","in":"query","description":"Describes optional properties that should be included in the response. You may declare multiple. (subscribed)","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["subscribed"]}}},{"name":"states","in":"query","description":"state of the alert","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["INVESTIGATING","IDENTIFIED","MONITORING","RESOLVED"]}}},{"name":"services","in":"query","description":"service IDs of the incident's affected services","style":"form","explode":true,"schema":{"type":"array","items":{"type":"integer","format":"int64"}}},{"name":"from","in":"query","description":"from date, ISO-UTC e.g. 2021-05-25T21:24:56.771Z, based on reportTime","schema":{"type":"string","format":"date-time"}},{"name":"until","in":"query","description":"until date, ISO-UTC e.g. 2021-05-26T21:24:56.771Z, based on reportTime","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"The incidents","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Incident"}}}}}}}}}}
```
## Create a new incident.
> Note: depending on affected services this will publish notifications to subscribers. Use /publish-info to forecast notifications.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.5-r.3"},"tags":[{"name":"Incidents"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"IncidentNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"summary":{"type":"string"},"status":{"$ref":"#/components/schemas/IncidentStatus"},"message":{"type":"string"},"sendNotification":{"type":"boolean"},"createdAt":{"type":"string","description":"May be overwritten during the creation of the incident, otherwise read-only","format":"date-time"},"updatedAt":{"type":"string","description":"May be overwritten during the creation of the incident, otherwise read-only","format":"date-time"},"affectedServices":{"type":"array","items":{"type":"object","properties":{"impact":{"$ref":"#/components/schemas/ServiceStatus"},"service":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}},"resolvedOn":{"type":"string","format":"date-time","readOnly":true}}},"IncidentStatus":{"type":"string","description":"the incident status","enum":["INVESTIGATING","IDENTIFIED","MONITORING","RESOLVED"]},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}}}},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}}}},"paths":{"/incidents":{"post":{"tags":["Incidents"],"summary":"Create a new incident.","description":"Note: depending on affected services this will publish notifications to subscribers. Use /publish-info to forecast notifications.","requestBody":{"description":"the incident","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentNoIncludes"}}},"required":true},"responses":{"200":{"description":"The newly created incident","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentNoIncludes"}}}}}}}}}
```
## Forecast the affected subscribers and status pages
> Forecast the affected subscribers and status pages as well as notifications that would be send out due to created or update incident.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.5-r.3"},"tags":[{"name":"Incidents"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"IncidentNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"summary":{"type":"string"},"status":{"$ref":"#/components/schemas/IncidentStatus"},"message":{"type":"string"},"sendNotification":{"type":"boolean"},"createdAt":{"type":"string","description":"May be overwritten during the creation of the incident, otherwise read-only","format":"date-time"},"updatedAt":{"type":"string","description":"May be overwritten during the creation of the incident, otherwise read-only","format":"date-time"},"affectedServices":{"type":"array","items":{"type":"object","properties":{"impact":{"$ref":"#/components/schemas/ServiceStatus"},"service":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}},"resolvedOn":{"type":"string","format":"date-time","readOnly":true}}},"IncidentStatus":{"type":"string","description":"the incident status","enum":["INVESTIGATING","IDENTIFIED","MONITORING","RESOLVED"]},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}}}},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}},"UIMenuItem":{"type":"object","properties":{"id":{"type":"number"},"label":{"type":"string"}}}}},"paths":{"/incidents/publish-info":{"post":{"tags":["Incidents"],"summary":"Forecast the affected subscribers and status pages","description":"Forecast the affected subscribers and status pages as well as notifications that would be send out due to created or update incident.","requestBody":{"description":"the incident","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentNoIncludes"}}},"required":true},"responses":{"200":{"description":"The forecast for the provided incident","content":{"application/json":{"schema":{"type":"object","properties":{"statusPagesInfo":{"$ref":"#/components/schemas/UIMenuItem"},"privateStatusPages":{"type":"number","readOnly":true},"publicStatusPages":{"type":"number","readOnly":true},"privateSubscribers":{"type":"number","readOnly":true},"publicSubscribers":{"type":"number","readOnly":true}}}}}}}}}}}
```
## Get a specific incident.
> Note: returns an ETag header that can be send to the PUT /incidents/{id} resource as If-Match header to return a 412 Error in case any related resources e.g. Services or Incident have been updated in the mean time.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.5-r.3"},"tags":[{"name":"Incidents"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"IncidentWithHistory":{"type":"object","properties":{"id":{"type":"number"},"summary":{"type":"string"},"status":{"$ref":"#/components/schemas/IncidentStatus"},"message":{"type":"string"},"sendNotification":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"history":{"type":"array","items":{"$ref":"#/components/schemas/IncidentUpdate"}},"affectedServices":{"type":"array","items":{"type":"object","properties":{"impact":{"$ref":"#/components/schemas/ServiceStatus"},"service":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}},"resolvedOn":{"type":"string","format":"date-time","readOnly":true},"subscribed":{"type":"boolean","readOnly":true},"affectedTeams":{"type":"array","readOnly":true,"items":{"$ref":"#/components/schemas/TeamRel"}}}},"IncidentStatus":{"type":"string","description":"the incident status","enum":["INVESTIGATING","IDENTIFIED","MONITORING","RESOLVED"]},"IncidentUpdate":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"creator":{"$ref":"#/components/schemas/UserRel"},"incidentStatus":{"$ref":"#/components/schemas/IncidentStatus"},"sendNotification":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"UserRel":{"required":["id"],"type":"object","properties":{"id":{"type":"integer","format":"int64"},"firstName":{"type":"string"},"lastName":{"type":"string"}}},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}}}},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}}}},"paths":{"/incidents/{id}":{"get":{"tags":["Incidents"],"summary":"Get a specific incident.","description":"Note: returns an ETag header that can be send to the PUT /incidents/{id} resource as If-Match header to return a 412 Error in case any related resources e.g. Services or Incident have been updated in the mean time.","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}},{"name":"include","in":"query","description":"Describes optional properties that should be included in the response. You may declare multiple. (subscribed, affectedTeams, history)","style":"form","explode":true,"schema":{"type":"array","items":{"type":"string","enum":["subscribed","affectedTeams","history"]}}}],"responses":{"200":{"description":"The requested incident","headers":{"ETag":{"description":"Send to the PUT /incidents/{id} resource as If-Match header to return a 412 Error in case any related resources e.g. Services or Incident have been updated in the mean time.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentWithHistory"}}}}}}}}}
```
## Update the specific incident.
> Note: the update will be automatically appended to the incident's update history and publish notifications to subscribers.
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.5-r.3"},"tags":[{"name":"Incidents"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"IncidentNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"summary":{"type":"string"},"status":{"$ref":"#/components/schemas/IncidentStatus"},"message":{"type":"string"},"sendNotification":{"type":"boolean"},"createdAt":{"type":"string","description":"May be overwritten during the creation of the incident, otherwise read-only","format":"date-time"},"updatedAt":{"type":"string","description":"May be overwritten during the creation of the incident, otherwise read-only","format":"date-time"},"affectedServices":{"type":"array","items":{"type":"object","properties":{"impact":{"$ref":"#/components/schemas/ServiceStatus"},"service":{"$ref":"#/components/schemas/ServiceNoIncludes"}}}},"resolvedOn":{"type":"string","format":"date-time","readOnly":true}}},"IncidentStatus":{"type":"string","description":"the incident status","enum":["INVESTIGATING","IDENTIFIED","MONITORING","RESOLVED"]},"ServiceStatus":{"type":"string","description":"the service status","enum":["OPERATIONAL","UNDER_MAINTENANCE","DEGRADED","PARTIAL_OUTAGE","MAJOR_OUTAGE"]},"ServiceNoIncludes":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"alias":{"type":"string"},"status":{"$ref":"#/components/schemas/ServiceStatus"},"description":{"type":"string"},"oneOpenIncidentOnly":{"type":"boolean"},"showUptimeHistory":{"type":"boolean"},"teams":{"type":"array","items":{"$ref":"#/components/schemas/TeamRel"}}}},"TeamRel":{"type":"object","properties":{"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}}}},"paths":{"/incidents/{id}":{"put":{"tags":["Incidents"],"summary":"Update the specific incident.","description":"Note: the update will be automatically appended to the incident's update history and publish notifications to subscribers.","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}},{"name":"If-Match","in":"header","description":"Should be the ETag response header retrieved from GET /incidents/{id} to prevent updating the incident based on outdated information. Will return 412 status code in case of conflict.","schema":{"type":"string"}}],"requestBody":{"description":"the incident","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentNoIncludes"}}},"required":true},"responses":{"200":{"description":"The updated incident","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncidentNoIncludes"}}}}}}}}}
```
## GET /incidents/{id}/private-subscribers
> Get the subscribers (users and teams) of an incident
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.5-r.3"},"tags":[{"name":"Incidents"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"TeamUserOption":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"type":{"type":"string","enum":["USER","TEAM"]}}}}},"paths":{"/incidents/{id}/private-subscribers":{"get":{"tags":["Incidents"],"summary":"Get the subscribers (users and teams) of an incident","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}}],"responses":{"200":{"description":"The subscribers of the incident","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamUserOption"}}}}}}}}}}
```
## POST /incidents/{id}/private-subscribers
> Add subscribers (users and teams) to an incident
```json
{"openapi":"3.0.1","info":{"title":"ilert REST API","version":"v2.2026.5-r.3"},"tags":[{"name":"Incidents"}],"servers":[{"url":"/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","description":"The Bearer API key of your user more info.","name":"Authorization","in":"header"}},"schemas":{"TeamUserOption":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"type":{"type":"string","enum":["USER","TEAM"]}}}}},"paths":{"/incidents/{id}/private-subscribers":{"post":{"tags":["Incidents"],"summary":"Add subscribers (users and teams) to an incident","parameters":[{"name":"id","in":"path","description":"entity ID","required":true,"schema":{"type":"number"}}],"requestBody":{"description":"subscribers that should be added","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/TeamUserOption"}}}},"required":true},"responses":{"204":{"description":"the response","content":{}}}}}}}
```
---
# Agent Instructions: 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:
```
GET https://docs.ilert.com/developer-docs/rest-api/api-reference/incidents.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.