openapi: 3.0.3
info:
  title: Oncall Service API
  description: Stable machine-to-machine API for querying on-call assignments.
  version: 1.0.0
servers:
  - url: /
    description: Relative API base
security:
  - serviceBearer: []
tags:
  - name: Oncall
    description: Read-only on-call assignment queries
paths:
  /api/v1/oncall/teams/{ref}/current-oncall:
    get:
      tags:
        - Oncall
      operationId: getTeamCurrentOncall
      summary: Get the current primary and backup on-call engineers for a team
      parameters:
        - name: ref
          in: path
          required: true
          description: Stable team slug or numeric team ID.
          schema:
            type: string
            minLength: 1
        - name: at_time
          in: query
          required: false
          description: Unix timestamp in seconds. Defaults to the server's current time.
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: Current on-call assignment.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurrentOncallResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthenticated"
        "403":
          $ref: "#/components/responses/PermissionDenied"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
components:
  securitySchemes:
    serviceBearer:
      type: http
      scheme: bearer
      bearerFormat: OncallServiceKey
      description: Service API key with the oncall:read scope.
  responses:
    BadRequest:
      description: The request is invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthenticated:
      description: Authentication is missing or invalid.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    PermissionDenied:
      description: The authenticated principal lacks the required scope.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    InternalError:
      description: The service could not complete the request.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    CurrentOncallResponse:
      type: object
      required:
        - team_id
        - at_time
        - current_engineer_emails
        - backup_engineer_emails
        - current_no_oncall
        - next_switch_at
        - manager_emails
      properties:
        team_id:
          type: integer
          format: int64
          minimum: 1
        at_time:
          type: integer
          format: int64
          description: Effective query time as a Unix timestamp in seconds.
        current_engineer_emails:
          type: array
          items:
            type: string
            format: email
        backup_engineer_emails:
          type: array
          items:
            type: string
            format: email
        current_no_oncall:
          type: boolean
        next_switch_at:
          type: integer
          format: int64
          description: Next schedule boundary as a Unix timestamp in seconds; zero when unknown.
        manager_emails:
          type: array
          description: >-
            The team's managers, sorted. Independent of at_time; use as the
            escalation target when no one is on call.
          items:
            type: string
            format: email
    ErrorResponse:
      type: object
      required:
        - code
        - message
        - error
      properties:
        code:
          type: string
          example: TEAM_NOT_FOUND
        message:
          type: string
          example: team does not exist
        error:
          type: string
          deprecated: true
          description: Backward-compatible alias of message.