openapi: 3.0.1
info:
  title: ilert REST Alert Actions Incidents API
  description: "# Introduction\nThe ilert API is a [RESTful](https://en.wikipedia.org/wiki/Representational_state_transfer) API and provides programmatic access to entities in ilert and lets you easily integrate ilert with 3rd party tools. If you are looking to develop an inbound integration (e.g. for a monitoring tool), please use our [Events API](#tag/events). \n\nThe API supports the JSON content type for requests and responses. The response content type is requested via the HTTP Accept header (`application/json`). All resources are accessible via https and are located at `api.ilert.com/api`. \n\n You may download ilert's latest [OpenAPI.json {...} here](https://api.ilert.com/api-docs/openapi.json).\n\n If you are looking for a classic Swagger-UI view you may also open [this link](https://api.ilert.com/api-docs/swagger-ui). \n\n ## Authentication\nThe REST API accepts bearer API tokens. Each user may create API keys using the ilert web application. Note: Make sure to send the `Bearer ` prefix e.g. `Bearer APIKEY` when sending api key requests. By default, access to all resources (using any method) requires the client to be authenticated.\n\n ## Team Context\n When using API tokens, the currently selected team context of the user will not be taken into account, i.e. list results will always return all entities to which the user has a view permission. When using basic auth credentials the currently selected team context of the user will be used to filter resource results. The context may be overwritten for API key calls using the `team-context` HTTP header. Specifying `0` for ALL teams, `-1` for MY teams or a specific team id e.g. `team-context=901` to fetch results for a certain team.  \n\n ## Errors\nilert uses HTTP response codes to indicate success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate a client error (e.g. a missing required parameter) and codes in the 5xx range indicate an error with ilert's servers. In case of an error, the response body contains the following information:\n\n Attribute     | Description \n ------------- | ------------- \n status  | the corresponsing HTTP status code  \n message  | a human readable description of the error \n code  | error code, used to identify error type  \n\n ## API Versioning\nChanges to our API are always backwards-compatible. To get more information about our API versioning and historical changes, please <a href='https://docs.ilert.com/rest-api/api-version-history' target='_blank'>take a look here</a>."
  version: v2.2026.5-r.3
  x-logo:
    url: ./ilert-logo-spaced.png
    backgroundColor: '#fafafa'
    altText: ilert documentation logo
servers:
- url: /api
security:
- apiKey: []
tags:
- name: Incidents
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'
    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'
      x-codegen-request-body-name: incident
  /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
      x-codegen-request-body-name: incident
  /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'
    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'
      x-codegen-request-body-name: incident
  /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:
      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: {}
      x-codegen-request-body-name: subscribers
components:
  schemas:
    ServiceStatus:
      type: string
      description: the service status
      enum:
      - OPERATIONAL
      - UNDER_MAINTENANCE
      - DEGRADED
      - PARTIAL_OUTAGE
      - MAJOR_OUTAGE
    TeamRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    UserRel:
      required:
      - id
      type: object
      properties:
        id:
          type: integer
          format: int64
        firstName:
          type: string
        lastName:
          type: string
    IncidentStatus:
      type: string
      description: the incident status
      enum:
      - INVESTIGATING
      - IDENTIFIED
      - MONITORING
      - RESOLVED
    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'
    UIMenuItem:
      type: object
      properties:
        id:
          type: number
        label:
          type: string
    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
    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
    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'
    TeamUserOption:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        type:
          type: string
          enum:
          - USER
          - TEAM
    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'
  securitySchemes:
    apiKey:
      type: apiKey
      description: The Bearer API key of your user <a href='/api-docs/#section/Authentication'>more info</a>.
      name: Authorization
      in: header
x-original-swagger-version: '2.0'