ilert REST API

openapi: 3.0.1
info:
  title: ilert REST 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: Numbers
- name: Integrations
- name: Events
- name: Series
- name: Deployment Events
- name: Users
- name: Contacts
- name: Notification Preferences
- name: Escalation Policies
- name: Schedules
- name: Alert Sources
- name: Heartbeat Monitors
- name: Alerts
- name: Alert Actions
- name: Support Hours
- name: Log-Entries
- name: Notifications
- name: Connectors
- name: Teams
- name: On-Calls
- name: Maintenance Windows
- name: Incident Templates
- name: Services
- name: Service Outages
- name: Incidents
- name: Metrics
- name: Metric Data Sources
- name: Status Pages
- name: Deployment Pipelines
- name: Event Flows
- name: Call Flows
- name: Call Flow Numbers
- name: Reports
paths:
  /users/{user-id}:
    get:
      tags:
      - Users
      summary: Get the specified user.
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: the user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      tags:
      - Users
      summary: Update an existing user.
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      requestBody:
        description: the user object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
        required: false
      responses:
        '200':
          description: the updated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-codegen-request-body-name: user
    delete:
      tags:
      - Users
      summary: Delete the specified user.
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '204':
          description: if deletion was successful
          content: {}
  /users/{user-id}/contacts/emails:
    get:
      tags:
      - Contacts
      summary: Get a user's emails
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContactEmail'
    post:
      tags:
      - Contacts
      summary: Create a new email
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactEmailPost'
        required: true
      responses:
        '201':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactEmail'
      x-codegen-request-body-name: user email contact
  /users/{user-id}/contacts/emails/{id}:
    get:
      tags:
      - Contacts
      summary: Get a specific email
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactEmail'
    put:
      tags:
      - Contacts
      summary: Update a user's email
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactEmailPost'
        required: false
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactEmail'
      x-codegen-request-body-name: user email contact
    delete:
      tags:
      - Contacts
      summary: Delete the user's specified email
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: if deletion was successful
          content: {}
  /users/{user-id}/contacts/phone-numbers:
    get:
      tags:
      - Contacts
      summary: Get a user's phone numbers
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContactPhoneNumber'
    post:
      tags:
      - Contacts
      summary: Create a phone number
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactPhoneNumberPost'
        required: true
      responses:
        '201':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactPhoneNumber'
      x-codegen-request-body-name: user phone number contact
  /users/{user-id}/contacts/phone-numbers/{id}:
    get:
      tags:
      - Contacts
      summary: Get specific phone number
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactPhoneNumber'
    put:
      tags:
      - Contacts
      summary: Update a user's phone number
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactPhoneNumberPost'
        required: false
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactPhoneNumber'
      x-codegen-request-body-name: user phone number contact
    delete:
      tags:
      - Contacts
      summary: Delete the user's specified phone number
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: if deletion was successful
          content: {}
  /users/{user-id}/notification-preferences/alerts:
    get:
      tags:
      - Notification Preferences
      summary: Get alert notification preferences of a user
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationPreferencesAlert'
    post:
      tags:
      - Notification Preferences
      summary: Create an alert notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesAlertPost'
        required: true
      responses:
        '201':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesAlert'
      x-codegen-request-body-name: alert notification preference
  /users/{user-id}/notification-preferences/alerts/{id}:
    get:
      tags:
      - Notification Preferences
      summary: Get specific notification preferences alert
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesAlert'
    put:
      tags:
      - Notification Preferences
      summary: Update a user's alert notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesAlertPost'
        required: false
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesAlert'
      x-codegen-request-body-name: alert notification preference
    delete:
      tags:
      - Notification Preferences
      summary: Delete the user's specified notification preferences alert
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: if deletion was successful
          content: {}
  /users/{user-id}/notification-preferences/duties:
    get:
      tags:
      - Notification Preferences
      summary: Get duty notification preferences of a user
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationPreferencesDuty'
    post:
      tags:
      - Notification Preferences
      summary: Create a duty notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesDutyPost'
        required: true
      responses:
        '201':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesDuty'
      x-codegen-request-body-name: duty notification preference
  /users/{user-id}/notification-preferences/duties/{id}:
    get:
      tags:
      - Notification Preferences
      summary: Get specific notification preferences duty
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesDuty'
    put:
      tags:
      - Notification Preferences
      summary: Update a user's duty notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesDutyPost'
        required: false
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesDuty'
      x-codegen-request-body-name: duty notification preference
    delete:
      tags:
      - Notification Preferences
      summary: Delete the user's specified notification preferences duty
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: if deletion was successful
          content: {}
  /users/{user-id}/notification-preferences/updates:
    get:
      tags:
      - Notification Preferences
      summary: Get update notification preferences of a user
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationPreferencesUpdate'
    post:
      tags:
      - Notification Preferences
      summary: Create an update notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesUpdatePost'
        required: true
      responses:
        '201':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesUpdate'
      x-codegen-request-body-name: update notification preference
  /users/{user-id}/notification-preferences/updates/{id}:
    get:
      tags:
      - Notification Preferences
      summary: Get specific notification preferences update
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesUpdate'
    put:
      tags:
      - Notification Preferences
      summary: Update a user's update notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesUpdatePost'
        required: false
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesUpdate'
      x-codegen-request-body-name: update notification preference
    delete:
      tags:
      - Notification Preferences
      summary: Delete the user's specified notification preferences update
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: if deletion was successful
          content: {}
  /users/{user-id}/notification-preferences/subscriptions:
    get:
      tags:
      - Notification Preferences
      summary: Get subscription notification preferences of a user
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NotificationPreferencesSubscription'
    post:
      tags:
      - Notification Preferences
      summary: Create a subscription notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesSubscriptionPost'
        required: true
      responses:
        '201':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesSubscription'
      x-codegen-request-body-name: subscription notification preference
  /users/{user-id}/notification-preferences/subscriptions/{id}:
    get:
      tags:
      - Notification Preferences
      summary: Get specific notification preferences subscription
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesSubscription'
    put:
      tags:
      - Notification Preferences
      summary: Update a user's subscription notification preference
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NotificationPreferencesSubscriptionPost'
        required: false
      responses:
        '200':
          description: the response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationPreferencesSubscription'
      x-codegen-request-body-name: subscription notification preference
    delete:
      tags:
      - Notification Preferences
      summary: Delete the user's specified notification preferences subscription
      parameters:
      - name: user-id
        in: path
        description: numeric user id
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: if deletion was successful
          content: {}
  /numbers:
    get:
      tags:
      - Numbers
      summary: List available phone numbers that ilert uses to send voice and SMS
        notifications
      responses:
        '200':
          description: List of phone numbers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OutboundNumber'
      security: []
  /integrations:
    get:
      tags:
      - Integrations
      summary: 'List available inbound and outbound integrations. Note: this resource
        is paginated.'
      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 entities.
        schema:
          maximum: 100
          type: integer
          format: int32
          default: 50
      responses:
        '200':
          description: list of integrations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Integration'
      security: []
  /users:
    get:
      tags:
      - Users
      summary: List existing users.
      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 entities.
        schema:
          maximum: 100
          type: integer
          format: int32
          default: 50
      responses:
        '200':
          description: list of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      tags:
      - Users
      summary: Create a new user. Requires ADMIN privileges.
      parameters:
      - name: send-no-invitation
        in: query
        description: Provide ?send-no-invitation=true if you do not wish to send an
          invitation email.
        schema:
          type: boolean
          default: false
      description: "**Sample request**\n\n```json\nRequest URL: https://api.ilert.com/api/users\n\
        \n{\n  \"firstName\": \"John\",\n  \"lastName\": \"Doe\",\n  \"email\": \"\
        [email protected]\",\n  \"position\": \"Software Engineer\",\n}\n```\n\n**Response**\n\
        \n````json\n{\n  \"id\": 2188373,\n  \"firstName\": \"John\",\n  \"lastName\"\
        : \"Doe\",\n  \"email\": \"[email protected]\",\n  \"position\": \"Software Engineer\"\
        ,\n  \"timezone\": \"Europe/Berlin\",\n  \"language\": \"de\",\n  \"role\"\
        : \"RESPONDER\",\n }\n````\n"
      requestBody:
        description: the user object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPost'
        required: false
      responses:
        '201':
          description: Created. The URI of the created user entity is included in
            the Location header and the user object is included in the body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-codegen-request-body-name: user
  /users/search-email:
    post:
      tags:
      - Users
      summary: Find a user by email address.
      description: Search for a user by their email address within the scope of the
        current account. This endpoint uses POST instead of GET to prevent email addresses
        from being exposed in URLs, server access logs, and browser history.
      requestBody:
        description: the email to search for
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  description: the email address of the user to find
        required: true
      responses:
        '200':
          description: the matching user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: no user found with the given email address
  /users/current:
    get:
      tags:
      - Users
      summary: Get the currently authenticated user.
      responses:
        '200':
          description: user object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    put:
      tags:
      - Users
      summary: Update the current user.
      requestBody:
        description: user object
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPost'
        required: false
      responses:
        '200':
          description: the updated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
      x-codegen-request-body-name: user
  /alerts:
    get:
      tags:
      - Alerts
      summary: List alerts (optionally matching certain criteria that are specified
        by query parameters).
      description: "**Sample URLs**\n* List only alerts that are either in state `PENDING`\
        \ or `ACCEPTED`: <br /> https://api.ilert.com/api/alerts?states=PENDING&states=ACCEPTED\n\
        * List only alerts that belong to the alert source with ID `1243` or `1743`\
        \ and where user `jd` is a responder: <br />\n  https://api.ilert.com/api/alerts?sources=1243&sources=1743&responders=jd\n\
        * Paginate first batch for a range of alerts (note: query parameters should\
        \ be url encoded): <br />\n https://api.ilert.com/api/alerts?start-index=0&max-results=100&from=2021-03-01T21:24:56.771Z&until=2021-04-01T21:24:56.771Z\n\
        * Fetch next page, assuming equal to max-results were returned: <br/>\n https://api.ilert.com/api/alerts?start-index=100&max-results=100&from=2021-03-01T21:24:56.771Z&until=2021-04-01T21:24:56.771Z\n\
        * Pagination should be done based on the `reportTime` field using the parameters\
        \ `from` and `until` as well as `start-index`. When building a local alert\
        \ state store the `id` field should be used as identifier. The `alertKey`\
        \ field is not suitable for this, as it is used to group related alerts to\
        \ each other."
      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 entities.
        schema:
          maximum: 100
          type: integer
          format: int32
          default: 50
      - name: include
        in: query
        description: Describes optional properties that should be included in the
          response. You may declare multiple. (nextEscalationUser)
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - nextEscalationUser
      - name: states
        in: query
        description: state of the alert
        style: form
        explode: true
        schema:
          type: array
          items:
         

# --- truncated at 32 KB (257 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ilert/refs/heads/main/openapi/ilert-ilert-rest-api-openapi.yml