openapi: 3.0.1
info:
  title: ilert REST Alert Actions On-Calls 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: On-Calls
paths:
  /on-calls:
    get:
      tags:
      - On-Calls
      summary: List on-calls with flexible filters
      parameters:
      - name: policies
        in: query
        description: escalation policy ids to filter on call duties for
        schema:
          type: number
      - name: policy-levels
        in: query
        description: 'can be provided instead of ''policies'', must be a serialised and urlencoded JSON object e.g. ?policy-levels="{ "id": 12, "level": 1 }" where id is the policy id and level is the escalation level that should be included'
        schema:
          type: string
      - name: schedules
        in: query
        description: on call schedule ids to filter on call duties for
        schema:
          type: number
      - name: users
        in: query
        description: user ids to filter on call duties for
        schema:
          type: number
      - name: expand
        in: query
        description: 'include full entities for: policy, escalationPolicy or user'
        schema:
          type: string
      - name: from
        in: query
        description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, start of the time range, may not exceed 3 months in total span, defaults to current time
        schema:
          type: string
      - name: until
        in: query
        description: date-time ISO-UTC e.g. 2021-05-25T21:24:56.771Z, end of the time range, must be after 'from', defaults to current time
        schema:
          type: string
      - name: timezone
        in: query
        description: Time zone in which the results will be rendered, defaults to UTC
        schema:
          type: string
      - name: start-index
        in: query
        description: offset for the search results, defaults to 0
        schema:
          type: number
      - name: max-results
        in: query
        description: limit for the search results, defaults to 50, may not exceed 250
        schema:
          type: number
      responses:
        '200':
          description: returns a list of on-call objects for the searched window
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OnCall'
components:
  schemas:
    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
    EscalationRule:
      required:
      - escalationTimeout
      type: object
      properties:
        escalationTimeout:
          type: integer
        user:
          type: object
          properties:
            id:
              type: number
          description: 'This field (type: User) is deprecated, please use ''users'' instead'
        schedule:
          type: object
          properties:
            id:
              type: number
          description: 'This field (type: Schedule) is deprecated, please use ''schedules'' instead'
        team:
          type: object
          properties:
            id:
              type: number
          description: 'This field (type: Team) is deprecated, please use ''teams'' instead'
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserRel'
        schedules:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleRel'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
    Role:
      type: string
      enum:
      - STAKEHOLDER
      - GUEST
      - RESPONDER
      - USER
      - ADMIN
    User:
      required:
      - email
      - firstName
      - lastName
      type: object
      properties:
        id:
          type: integer
          format: int64
        firstName:
          type: string
        lastName:
          type: string
        email:
          type: string
        timezone:
          $ref: '#/components/schemas/TimeZone'
        position:
          type: string
        department:
          type: string
        avatarUrl:
          type: string
          readOnly: true
        language:
          type: string
          enum:
          - de
          - en
        region:
          type: string
          enum:
          - DE
          - GB
          - CH
          - CN
          - IN
          - US
          - FR
          - ES
          - CA
          - IE
        role:
          $ref: '#/components/schemas/Role'
        shiftColor:
          type: string
          description: Optional hex-color code for the user's shifts in schedules calendars
        mutedUntil:
          type: string
          description: Date in ISO-8601
          format: date-time
        createdAt:
          type: string
          description: Date in ISO-8601
          format: date-time
        updatedAt:
          type: string
          description: Date in ISO-8601
          format: date-time
    OnCall:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        escalationPolicy:
          $ref: '#/components/schemas/EscalationPolicy'
        schedule:
          $ref: '#/components/schemas/ScheduleRel'
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        escalationLevel:
          type: number
    ScheduleRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum:
          - STATIC
          - RECURRING
    EscalationPolicy:
      required:
      - escalationRules
      - name
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        escalationRules:
          type: array
          items:
            $ref: '#/components/schemas/EscalationRule'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
        repeating:
          type: boolean
          default: false
        frequency:
          maximum: 9
          minimum: 1
          type: integer
          format: int32
          default: 1
        delayMin:
          maximum: 15
          minimum: 0
          type: integer
          format: int32
          default: 0
        routingKey:
          type: string
          description: optional
    TimeZone:
      type: string
      enum:
      - Europe/Berlin
      - America/New_York
      - America/Los_Angeles
      - Asia/Istanbul
  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'