openapi: 3.0.3
info:
  title: University of St Andrews Service Status Components Notices API
  description: JSON API for the University of St Andrews service status page, hosted on the Sorry (Sorry App) status platform. Exposes overall page status, system components, and notices (incidents and maintenance). The API is read-only and public. Fair-use rate limiting applies at 10 requests per second, and collections paginate at a maximum of 25 records per page. Paths and schemas in this document were derived from the published API documentation at https://status.st-andrews.ac.uk/api and verified against live responses.
  version: v1
  contact:
    name: University of St Andrews
    url: https://status.st-andrews.ac.uk/
servers:
- url: https://status.st-andrews.ac.uk/api/v1
  description: Production v1 endpoint
tags:
- name: Notices
  description: Incidents and maintenance notices.
paths:
  /notices:
    get:
      operationId: listNotices
      summary: List notices
      description: Returns a paginated list of notices (incidents and maintenance), past, present, and future. Supports filtering by type and timeline state.
      tags:
      - Notices
      parameters:
      - name: filter[type_eq]
        in: query
        description: Filter notices by type.
        required: false
        schema:
          type: string
          enum:
          - general
          - planned
          - unplanned
      - name: filter[timeline_state_eq]
        in: query
        description: Filter notices by timeline state.
        required: false
        schema:
          type: string
          enum:
          - future
          - present
          - past_recent
          - past_distant
      - name: page
        in: query
        description: Page number for pagination.
        required: false
        schema:
          type: integer
          minimum: 1
      responses:
        '200':
          description: A paginated list of notices.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticesResponse'
  /notices/{id}:
    get:
      operationId: getNotice
      summary: Get detailed notice information
      description: Returns detailed information for a single notice, including the affected components and the full list of updates.
      tags:
      - Notices
      parameters:
      - name: id
        in: path
        description: The unique identifier of the notice.
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: The requested notice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoticeResponse'
components:
  schemas:
    NoticesResponse:
      type: object
      properties:
        notices:
          type: array
          items:
            $ref: '#/components/schemas/Notice'
        meta:
          $ref: '#/components/schemas/Meta'
    Update:
      type: object
      properties:
        id:
          type: integer
        state:
          type: string
        content:
          type: string
        url:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    NoticeDetail:
      allOf:
      - $ref: '#/components/schemas/Notice'
      - type: object
        properties:
          components:
            type: array
            items:
              $ref: '#/components/schemas/Component'
          updates:
            type: array
            items:
              $ref: '#/components/schemas/Update'
    Link:
      type: object
      properties:
        href:
          type: string
        count:
          type: integer
    NoticeResponse:
      type: object
      properties:
        notice:
          $ref: '#/components/schemas/NoticeDetail'
    Component:
      type: object
      properties:
        id:
          type: integer
        state:
          type: string
          enum:
          - operational
          - degraded
          - under_maintenance
        name:
          type: string
        description:
          type: string
        parent_id:
          type: integer
          nullable: true
        position:
          type: integer
        links:
          type: object
          properties:
            children:
              $ref: '#/components/schemas/Link'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Meta:
      type: object
      properties:
        count:
          type: integer
          description: Number of records on the current page (maximum 25).
        total_count:
          type: integer
          description: Total number of records across all pages.
        next_page:
          type: string
          nullable: true
          description: URL of the next page, if any.
    Notice:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
          - general
          - planned
          - unplanned
        timeline_state:
          type: string
          enum:
          - future
          - present
          - past_recent
          - past_distant
        state:
          type: string
          description: Current notice state, e.g. investigating, scheduled, recovering, resolved, complete, cancelled. Absent for general notices.
        subject:
          type: string
        url:
          type: string
          format: uri
        begins_at:
          type: string
          format: date-time
          nullable: true
        ends_at:
          type: string
          format: date-time
          nullable: true
        began_at:
          type: string
          format: date-time
          nullable: true
        ended_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        tag_list:
          type: array
          items:
            type: string
        links:
          type: object
          properties:
            self:
              type: string
        latest_update:
          $ref: '#/components/schemas/Update'