openapi: 3.1.0
info:
  version: '1.0'
  title: IMSU Alerts
  summary: IMSU Alert Manager
  description: 'Is my stream up alert manager. Operates a webhook for Prometheus Alertmanager to interact with. The API translates webhooks into database entries for a log of activities, as well as publishing MQTT messages for real time processing by 3rd party processes.'
  termsOfService: 'https://www.streamguys.com/tos'
  contact:
    name: Support
    url: 'https://support.streamguys.com'
    email: support@streamguys.com
  license:
    url: 'https://spdx.org/licenses/Apache-2.0.html'
    name: Apache 2.0
servers:
  - url: 'https://imsu-alerts.ismystreamup.com/api/v1'
    description: production
  - url: 'https://dev-imsu-alerts.ismystreamup.com/api/v1'
    description: development
paths:
  /alerts:
    get:
      summary: Get Alerts History
      description: Get alerts. Optionally filter for Client or Region or both. Combine with start and end time filtering for concise responses.
      operationId: get-alerts
      parameters:
        - $ref: '#/components/parameters/client_id'
        - $ref: '#/components/parameters/region_id'
        - $ref: '#/components/parameters/time_start'
        - $ref: '#/components/parameters/time_end'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          $ref: '#/components/responses/alerts'
      security:
        - x-imsu-key: []
      servers:
        - url: 'https://imsu-alerts.ismystreamup.com/api/v1'
          description: production
        - url: 'https://dev-imsu-alerts.ismystreamup.com/api/v1'
          description: development
  '/alert/{service_id}':
    get:
      summary: Get Alert History
      description: 'Get alert history for a given service, optionally filter by region.  Combine with start and end time filtering for concise responses.'
      operationId: get-alerts-service_id
      parameters:
        - $ref: '#/components/parameters/region_id'
        - $ref: '#/components/parameters/time_start'
        - $ref: '#/components/parameters/time_end'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: service_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          $ref: '#/components/responses/alert'
        '404':
          description: Not Found
        '':
          $ref: '#/components/responses/alert'
      security:
        - x-imsu-key: []
      servers:
        - url: 'https://imsu-alerts.ismystreamup.com/api/v1'
          description: production
        - url: 'https://dev-imsu-alerts.ismystreamup.com/api/v1'
          description: development
components:
  parameters:
    client_id:
      name: client_id
      in: query
      description: The ID of the client to filter alerts for.
      required: false
      schema:
        type: string
    region_id:
      name: region_id
      in: query
      description: The region to filter results for.
      required: false
      schema:
        type: string
    time_start:
      name: time_start
      in: query
      description: Filter the resolved time of alerts to after this epoch timestamp.
      required: false
      schema:
        type: integer
    time_end:
      name: time_end
      in: query
      description: Filter the resolved time of alerts to before this epoch timestamp.
      required: false
      schema:
        type: integer
    service_id:
      name: service_id
      in: path
      description: The ID of the service to interact with.
      required: true
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Limit the number of alerts returned.
      required: false
      schema:
        type: integer
        default: 100
    offset:
      name: offset
      in: query
      description: The number of alerts to skip before starting to return results.
      required: false
      schema:
        type: integer
        default: 0
  securitySchemes:
    x-imsu-key:
      type: apiKey
      name: x-imsu-key
      in: header
  responses:
    alert:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/alert'
          examples:
            Example 1:
              value:
                id: f0127218-8a42-11ef-9184-c64b6e39751d
                client_id: 5b3fa7ba-57d3-4017-a65b-d57dcd2db643
                service_id: f0bca486-8a42-11ef-925a-c64b6e39751d
                status: firing
                region_id: us-west
                started: '2019-08-24T14:15:02Z'
                last_update: '2019-08-24T14:15:22Z'
                duration: 20
                details: 404 File Not Found
    alerts:
      description: Example response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/alerts'
          examples:
            Example 1:
              value:
                - id: f0127218-8a42-11ef-9184-c64b6e39751d
                  client_id: 5b3fa7ba-57d3-4017-a65b-d57dcd2db643
                  service_id: f0bca486-8a42-11ef-925a-c64b6e39751d
                  status: firing
                  region_id: us-west
                  started: '2019-08-24T14:15:02Z'
                  last_update: '2019-08-24T14:15:22Z'
                  duration: 20
                  details: 404 File Not Found
  schemas:
    alert:
      type: object
      title: alert
      description: Alert details
      properties:
        id:
          type: string
          description: The unique ID of the alert (UUIDv7).
          format: uuid
          readOnly: true
        client_id:
          type: string
          description: The unique ID of the client (UUIDv7).
          format: uuid
          readOnly: true
        service_id:
          type: string
          description: The unique ID of the service (UUIDv7).
          format: uuid
          readOnly: true
        status:
          enum:
            - firing
            - resolved
          description: The active status of the alert.
          readOnly: true
        region_id:
          type: string
          description: The region this alert was fired from.
          pattern: '[a-z]{2,4}\-[a-z0-9]{4,8}'
          readOnly: true
          examples:
            - us-west
        started:
          type: string
          description: The spawn time of the alert.
          format: date-time
          readOnly: true
        last_update:
          type: string
          description: The last time an update for the alert was recieved.
          format: date-time
        duration:
          type: integer
          description: Duration of the alert in seconds.
          format: int64
          readOnly: true
        details:
          type: string
          description: Details passed by the monitoring system.
          readOnly: true
      examples:
        - id: 1231451
          client_id: 5b3fa7ba-57d3-4017-a65b-d57dcd2db643
          service_id: 123415
          status: firing
          region_id: us-west
          started: '2019-08-24T14:15:02Z'
          last_update: '2019-08-24T14:15:22Z'
          duration: 20
          details: 404 File Not Found
    alerts:
      type: array
      title: alerts
      description: A list of alerts.
      items:
        $ref: '#/components/schemas/alert'
security:
  - x-imsu-key: []
