ilert Schedules API

openapi: 3.2.0
info:
  title: ilert REST Schedules API
  description: '# Introduction

    The ilert API is a RESTful API and provides programmatic access to entities in ilert and lets you easily integrate ilert with 3rd party tools.'
  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'
      operationId: getSchedules
      x-operation-id-source: derived
    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
      operationId: postSchedules
      x-operation-id-source: derived
  /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'
      operationId: getSchedulesById
      x-operation-id-source: derived
    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
      operationId: putSchedulesById
      x-operation-id-source: derived
    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: {}
      operationId: deleteSchedulesById
      x-operation-id-source: derived
  /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'
      operationId: getSchedulesByIdShifts
      x-operation-id-source: derived
  /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'
      operationId: getSchedulesByIdOverrides
      x-operation-id-source: derived
    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
      operationId: putSchedulesByIdOverrides
      x-operation-id-source: derived
  /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: {}
      operationId: getSchedulesByIdUserOnCall
      x-operation-id-source: derived
components:
  schemas:
    ShiftRel:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/UserRel'
        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
    Shift:
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
        end:
          type: string
          format: date-time
        start:
          type: string
          format: date-time
    TimeZone:
      type: string
      enum:
      - Europe/Berlin
      - America/New_York
      - America/Los_Angeles
      - Asia/Istanbul
    TimeOfWeek:
      required:
      - dayOfWeek
      - time
      type: object
      properties:
        dayOfWeek:
          type: string
          enum:
          - MONDAY
          - TUESDAY
          - WEDNESDAY
          - THURSDAY
          - FRIDAY
          - SATURDAY
          - SUNDAY
        time:
          type: string
          format: '15:00'
    Role:
      type: string
      enum:
      - STAKEHOLDER
      - GUEST
      - RESPONDER
      - USER
      - ADMIN
    ScheduleRel:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          type: string
          enum:
          - STATIC
          - RECURRING
    ScheduleLayerRestriction:
      required:
      - from
      - to
      type: object
      properties:
        from:
          $ref: '#/components/schemas/TimeOfWeek'
        to:
          $ref: '#/components/schemas/TimeOfWeek'
    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
    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'
    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'
  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'