openapi: 3.0.1
info:
  title: ilert REST Alert Actions Schedules 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: Schedules
paths:
  /schedules:
    get:
      tags:
      - Schedules
      summary: List on-call schedules.
      parameters:
      - name: include
        in: query
        description: Describes optional properties that should be included in the response. You may declare multiple. (currentShift, nextShift, scheduleLayers [only available for RECURRING schedules], shifts [only available for STATIC schedules], past [show shifts in the past, only for STATIC])
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - scheduleLayers
            - shifts
            - currentShift
            - nextShift
            - past
      - 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 schedules.
        schema:
          maximum: 20
          type: integer
          format: int32
          default: 20
      responses:
        '200':
          description: a list of on-call schedules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'
    post:
      tags:
      - Schedules
      summary: Create a new on-call schedule.
      parameters:
      - name: abort-on-gaps
        in: query
        description: Used for static schedules to prevent creating schedules with gaps
        schema:
          type: boolean
      requestBody:
        description: The on-call schedule. (scheduleLayers [only available for RECURRING schedules], shifts [only available for STATIC schedules])
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schedule'
        required: true
      responses:
        '201':
          description: The created on-call schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
      x-codegen-request-body-name: schedule
  /schedules/{id}:
    get:
      tags:
      - Schedules
      summary: Get the on-call schedule with the specified id.
      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. (currentShift, nextShift, scheduleLayers [only available for RECURRING schedules], shifts [only available for STATIC schedules], past [show shifts in the past, only for STATIC])
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - scheduleLayers
            - shifts
            - currentShift
            - nextShift
            - past
      responses:
        '200':
          description: The schedule object. (scheduleLayers [only available for RECURRING schedules], shifts [only available for STATIC schedules])
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
    put:
      tags:
      - Schedules
      summary: Update an on-call schedule.
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      - name: abort-on-gaps
        in: query
        description: Used for static schedules to prevent updating schedules with gaps
        schema:
          type: boolean
      requestBody:
        description: The on-call schedule. (scheduleLayers [only available for RECURRING schedules], shifts [only available for STATIC schedules])
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Schedule'
        required: true
      responses:
        '200':
          description: The updated on-call schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
      x-codegen-request-body-name: schedule
    delete:
      tags:
      - Schedules
      summary: Delete the on-call schedule with the specified id.
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '204':
          description: empty response
          content: {}
  /schedules/{id}/shifts:
    get:
      tags:
      - Schedules
      summary: Get shifts for the specified schedule and date range.
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      - name: from
        in: query
        description: from date, default is start of last month
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        description: until date, default is from date plus 3 months
        schema:
          type: string
      - name: exclude-overrides
        in: query
        description: if true, shifts won't include overrides
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: the shift objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shift'
  /schedules/{id}/overrides:
    get:
      tags:
      - Schedules
      summary: Get overrides for the specified schedule.
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the shift objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Shift'
    put:
      tags:
      - Schedules
      summary: Add an override shift to a schedule.
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      requestBody:
        description: the shift which should overwrite the schedule (must not be in the past)
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shift'
        required: true
      responses:
        '200':
          description: the overwritten schedule object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScheduleRel'
      x-codegen-request-body-name: shift
  /schedules/{id}/user-on-call:
    get:
      tags:
      - Schedules
      summary: Get the user (wrapped in a shift object) on-call for the specified schedule.
      parameters:
      - name: id
        in: path
        description: entity ID
        required: true
        schema:
          type: number
      responses:
        '200':
          description: the current shift
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shift'
        '204':
          description: if no user is on-call
          content: {}
components:
  schemas:
    TimeZone:
      type: string
      enum:
      - Europe/Berlin
      - America/New_York
      - America/Los_Angeles
      - Asia/Istanbul
    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
    ShiftRel:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserRel'
        end:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
    ScheduleLayerConfig:
      required:
      - rotation
      - startsOn
      - users
      type: object
      properties:
        name:
          type: string
        startsOn:
          type: string
          format: date-time
        endsOn:
          type: string
          format: date-time
        users:
          type: array
          items:
            $ref: '#/components/schemas/UserRel'
        rotation:
          type: string
          format: P7D
        restrictionType:
          type: string
          description: 'Note: ''TIMES_OF_DAY'' is just a UI state representation, the API always uses ''TIMES_OF_WEEK'''
          enum:
          - TIMES_OF_WEEK
        restrictions:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleLayerRestriction'
    Role:
      type: string
      enum:
      - STAKEHOLDER
      - GUEST
      - RESPONDER
      - USER
      - ADMIN
    Schedule:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        timezone:
          $ref: '#/components/schemas/TimeZone'
        type:
          type: string
          enum:
          - STATIC
          - RECURRING
        scheduleLayers:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleLayerConfig'
        shifts:
          type: array
          items:
            $ref: '#/components/schemas/ShiftRel'
        showGaps:
          type: boolean
        defaultShiftDuration:
          type: string
          format: P7D
        currentShift:
          $ref: '#/components/schemas/ShiftRel'
        nextShift:
          $ref: '#/components/schemas/ShiftRel'
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamRel'
    Shift:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        end:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
    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
    ScheduleRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum:
          - STATIC
          - RECURRING
    TimeOfWeek:
      required:
      - dayOfWeek
      - time
      type: object
      properties:
        dayOfWeek:
          type: string
          enum:
          - MONDAY
          - TUESDAY
          - WEDNESDAY
          - THURSDAY
          - FRIDAY
          - SATURDAY
          - SUNDAY
        time:
          type: string
          format: '15:00'
    ScheduleLayerRestriction:
      required:
      - from
      - to
      type: object
      properties:
        from:
          $ref: '#/components/schemas/TimeOfWeek'
        to:
          $ref: '#/components/schemas/TimeOfWeek'
  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'