openapi: 3.0.0
info:
  title: Alerts API
  version: '1.0'
  description: >-
    The Tidepool API is an HTTP REST API used by Tidepool clients to communicate
    with the Tidepool Platform.


    For more information, see the [Getting Started](../docs/quick-start.md)
    section.
  termsOfService: https://developer.tidepool.org/terms-of-use/
  contact:
    name: API Support
    url: https://support.tidepool.org/
    email: support@tidepool.org
  license:
    name: BSD-2-Clause
    url: https://github.com/tidepool-org/hydrophone/blob/master/LICENSE
  x-tidepool-service: https://github.com/tidepool-org/hydrophone
servers:
  - url: https://external.integration.tidepool.org
    description: integration
  - url: https://api.tidepool.org
    description: production
  - url: https://dev1.dev.tidepool.org
    description: dev1
  - url: https://qa1.development.tidepool.org
    description: qa1
  - url: https://qa2.development.tidepool.org
    description: qa2
security:
  - sessionToken: []
tags:
  - name: Alerts
    description: Endpoints related to alert configuration and management.
paths:
  /v1/users/{userId}/followers/{followerUserId}/alerts:
    parameters:
      - $ref: '#/components/parameters/userId'
      - $ref: '#/components/parameters/followerUserId'
    delete:
      summary: Delete an alerts configuration
      description: Delete an existing alerts configuration.
      operationId: DeleteAlertsConfiguration
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Alerts
    get:
      summary: Get an alerts configuration
      description: Retrieve an existing alerts configuration.
      operationId: GetAlertsConfiguration
      responses:
        '200':
          $ref: '#/components/responses/AlertsConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Alerts
    post:
      summary: Create or update an alerts configuration
      description: |-
        Create or update an alerts configuration.
        If no alerts configuration exists, it will be created.
      operationId: UpsertAlertsConfiguration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/alertsconfig.v1'
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Alerts
components:
  securitySchemes:
    sessionToken:
      description: Tidepool Session Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
  responses:
    OK:
      description: OK
    BadRequest:
      description: Bad Request
    Unauthorized:
      description: Unauthorized
    Forbidden:
      description: Forbidden
    NotFound:
      description: Not Found
    ServerError:
      description: Server Error
    AlertsConfig:
      description: Alerts Config
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/alertsConfigReadOnly'
              - $ref: '#/components/schemas/alertsconfig.v1'
  parameters:
    userId:
      name: userId
      description: Tidepool User ID of the user who granted follow access.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
    followerUserId:
      name: followerUserId
      description: Tidepool User ID of the care partner to receive alerts.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
  schemas:
    tidepoolUserId:
      $ref: '#/components/schemas/tidepooluserid'
    alertsConfigReadOnly:
      type: object
      properties:
        uploadId:
          $ref: '#/components/schemas/uploadid.v1'
        userId:
          $ref: '#/components/schemas/tidepooluserid'
        followedUserId:
          $ref: '#/components/schemas/tidepooluserid'
    tidepooluserid:
      type: string
      title: Tidepool User ID
      pattern: >-
        ^([0-9a-f]{10}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
      description: >-
        String representation of a Tidepool User ID. Old style IDs are 10-digit
        strings consisting of only hexadeximcal digits. New style IDs are
        36-digit [UUID
        v4](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_4_(random))
      readOnly: true
      x-go-type: string
    uploadid.v1:
      title: Upload ID
      description: >-
        An upload identifier; this field should be the uploadId of the
        corresponding upload record
      type: string
      pattern: ^([0-9a-f]{32}|upid_[0-9a-f]{12})$
      minLength: 17
      maxLength: 32
      example: 0d92d5c1c22117a18f3620b9e24d3c06
      x-tags:
        - Data
    base.v1:
      type: object
      properties:
        enabled:
          type: boolean
          default: false
          description: A toggle for disabling the alert.
    unitsmgdl.v1:
      title: Blood Unit (mg/dL)
      type: string
      enum:
        - mg/dL
        - mg/dl
      example: mg/dL
      x-tags:
        - Data
    valuemgdl.v1:
      title: Blood Value (mg/dL)
      description: An integer value representing a `mg/dL` value.
      type: integer
      format: int32
      minimum: 0
      maximum: 1000
      example: 105
      x-tags:
        - Data
    glucosemgdl.v1:
      title: Blood Glucose (mg/dL)
      description: Blood glucose value, in `mg/dL`
      type: object
      properties:
        units:
          $ref: '#/components/schemas/unitsmgdl.v1'
        value:
          $ref: '#/components/schemas/valuemgdl.v1'
      required:
        - units
        - value
      x-tags:
        - Data
    unitsmmol.v1:
      title: Blood Unit (mmol/L)
      type: string
      enum:
        - mmol/L
        - mmol/l
      example: mmol/L
      x-tags:
        - Data
    valuemmol.v1:
      title: Blood Value (mmol/L)
      description: A floating point value representing a `mmol/L` value.
      type: number
      format: float
      minimum: 0
      example: 5.5
      x-tags:
        - Data
    glucosemmol.v1:
      title: Blood Glucose (mmol/L)
      description: Blood glucose value, in `mmol/L`
      type: object
      properties:
        units:
          $ref: '#/components/schemas/unitsmmol.v1'
        value:
          $ref: '#/components/schemas/valuemmol.v1'
      required:
        - units
        - value
      x-tags:
        - Data
    glucose.v1:
      title: Blood Glucose
      description: Blood glucose value, in `mg/dL` or `mmol/L`
      oneOf:
        - $ref: '#/components/schemas/glucosemgdl.v1'
        - $ref: '#/components/schemas/glucosemmol.v1'
      x-tags:
        - Data
    glucosethreshold.v1:
      type: object
      properties:
        threshold:
          $ref: '#/components/schemas/glucose.v1'
      required:
        - threshold
    delay.v1:
      type: object
      properties:
        delay:
          type: integer
          default: 0
          minimum: 0
          maximum: 120
          description: Duration in minutes to wait before alerting.
    repeat.v1:
      type: object
      properties:
        repeat:
          type: integer
          default: 0
          minimum: 0
          maximum: 240
          description: |-
            Duration in minutes, after which an alert will be repeated.
            A value of 0 disables the repeat functionality.
    alertsconfig.v1:
      type: object
      properties:
        urgentLow:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/glucosethreshold.v1'
            - type: object
              description: >-
                Blood glucose measurements at or below this value will trigger
                an immediate and urgent alert.
        low:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - $ref: '#/components/schemas/repeat.v1'
            - $ref: '#/components/schemas/glucosethreshold.v1'
            - type: object
              description: >-
                Blood glucose measurements at or below this value will trigger
                an alert.
        high:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - $ref: '#/components/schemas/repeat.v1'
            - $ref: '#/components/schemas/glucosethreshold.v1'
            - type: object
              description: >-
                Blood glucose measurements at or above this value will trigger
                an alert.
        noCommunication:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - type: object
              description: An alert sent when issues prevent the display of CGM data.
        notLooping:
          allOf:
            - $ref: '#/components/schemas/base.v1'
            - $ref: '#/components/schemas/delay.v1'
            - type: object
              description: An alert sent when the Tidepool Loop app is unable to loop.
      minProperties: 1
      description: >-
        Configuration for alerts triggered in response to the status of a user's
        device and data.
