openapi: 3.0.0
info:
  title: Devices API
  version: '1.0'
  description: >-
    The Tidepool API is an HTTP REST API used by Tidepool clients use 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: Tidepool
    url: https://www.tidepool.org/
    email: support@tidepool.org
  license:
    name: BSD-2-Clause
    url: https://github.com/tidepool-org/devices/blob/master/LICENSE
  x-tidepool-service: https://github.com/tidepool-org/devices
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: []
tags:
  - name: Devices
    description: >-
      List and retrieve information about Tidepool supported devices, such as
      insulin pumps and continuous glucose monitors (CGMs), including the guard
      rails used to validate device settings.
paths:
  /v1/devices/pumps:
    get:
      operationId: ListPumps
      summary: List Pumps
      description: List all Tidepool supported insulin pumps.
      responses:
        '200':
          $ref: '#/components/responses/PumpList'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Devices
  /v1/devices/pumps/{id}:
    parameters:
      - $ref: '#/components/parameters/deviceid.v1'
    get:
      operationId: GetPumpById
      summary: Get Pump by ID
      description: Get a Tidepool supported insulin pump by its unique device identifier.
      responses:
        '200':
          $ref: '#/components/responses/Pump'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Devices
  /v1/devices/cgms:
    get:
      operationId: ListCgms
      summary: List CGMs
      description: List all Tidepool supported continuous glucose monitors (CGMs).
      responses:
        '200':
          $ref: '#/components/responses/CgmList'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Devices
  /v1/devices/cgms/{id}:
    parameters:
      - $ref: '#/components/parameters/deviceid.v1'
    get:
      operationId: GetCgmById
      summary: Get CGM by ID
      description: >-
        Get a Tidepool supported continuous glucose monitor (CGM) by its unique
        device identifier.
      responses:
        '200':
          $ref: '#/components/responses/Cgm'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
        - Devices
components:
  responses:
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.v1'
    ServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error.v1'
    Pump:
      description: Insulin pump
      content:
        application/json:
          schema:
            title: Get Pump by ID Response
            type: object
            properties:
              pump:
                $ref: '#/components/schemas/pump.v1'
    PumpList:
      description: List of insulin pumps
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/pumplist.v1'
    Cgm:
      description: Continuous glucose monitor
      content:
        application/json:
          schema:
            title: Get CGM by ID Response
            type: object
            properties:
              cgm:
                $ref: '#/components/schemas/cgm.v1'
    CgmList:
      description: List of continuous glucose monitors
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/cgmlist.v1'
  schemas:
    guid.v1:
      title: GUID
      description: UUID v4 as defined in [RFC 4122](https://www.ietf.org/rfc/rfc4122.txt).
      type: string
      format: uuid
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      example: b9468a76-4afc-4c33-8d1d-1f08324d9160
      x-go-type: string
    bloodglucoseunits.v1:
      title: Blood Glucose Units
      description: Blood glucose units
      type: string
      enum:
        - MilligramsPerDeciliter
      default: MilligramsPerDeciliter
    fixeddecimal.v1:
      title: Fixed Decimal
      description: >-
        A fixed precision decimal number, expressed as whole units and nano
        (10^-9) units. For example, the value 5.75 is represented as `units` = 5
        and `nanos` = 750000000.
      type: object
      properties:
        units:
          description: The whole units of the amount
          type: integer
          format: int32
          example: 5
        nanos:
          description: Number of nano (10^-9) units of the amount
          type: integer
          format: int32
          example: 750000000
    recommendedbounds.v1:
      title: Recommended Bounds
      description: >-
        Tidepool recommended closed range of values. May be `null` if there are
        no recommended bounds for the setting.
      type: object
      nullable: true
      properties:
        minimum:
          $ref: '#/components/schemas/fixeddecimal.v1'
        maximum:
          $ref: '#/components/schemas/fixeddecimal.v1'
    absolutebounds.v1:
      title: Absolute Bounds
      description: Device specific closed range of allowed values
      type: object
      properties:
        minimum:
          $ref: '#/components/schemas/fixeddecimal.v1'
        maximum:
          $ref: '#/components/schemas/fixeddecimal.v1'
        increment:
          $ref: '#/components/schemas/fixeddecimal.v1'
    glucosesafetylimitguardrail.v1:
      title: Glucose Safety Limit Guard Rail
      description: Guard rail for the glucose safety limit setting
      type: object
      properties:
        units:
          $ref: '#/components/schemas/bloodglucoseunits.v1'
        recommendedBounds:
          $ref: '#/components/schemas/recommendedbounds.v1'
        absoluteBounds:
          $ref: '#/components/schemas/absolutebounds.v1'
    maxsegments.v1:
      title: Maximum Segments
      description: Maximum number of time segments
      type: integer
      format: int32
      example: 48
    insulinsensitivityguardrail.v1:
      title: Insulin Sensitivity Guard Rail
      description: Guard rail for the insulin sensitivity setting
      type: object
      properties:
        units:
          $ref: '#/components/schemas/bloodglucoseunits.v1'
        recommendedBounds:
          $ref: '#/components/schemas/recommendedbounds.v1'
        absoluteBounds:
          $ref: '#/components/schemas/absolutebounds.v1'
        maxSegments:
          $ref: '#/components/schemas/maxsegments.v1'
    basalrateunits.v1:
      title: Basal Rate Units
      description: Basal rate units
      type: string
      enum:
        - UnitsPerHour
      default: UnitsPerHour
    basalratesguardrail.v1:
      title: Basal Rates Guard Rail
      description: Guard rail for the basal rate schedule setting
      type: object
      properties:
        units:
          $ref: '#/components/schemas/basalrateunits.v1'
        defaultValue:
          description: >-
            Default value. May be `null` if the device has no default value for
            the setting.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/fixeddecimal.v1'
        absoluteBounds:
          description: >-
            Device specific absolute bounds. Some pumps might have different
            increments for different ranges.
          type: array
          items:
            $ref: '#/components/schemas/absolutebounds.v1'
        maxSegments:
          $ref: '#/components/schemas/maxsegments.v1'
    carbohydrateratiounits.v1:
      title: Carbohydrate Ratio Units
      description: Carbohydrate ratio units
      type: string
      enum:
        - GramsPerUnit
      default: GramsPerUnit
    carbohydrateratioguardrail.v1:
      title: Carbohydrate Ratio Guard Rail
      description: Guard rail for the carbohydrate ratio setting
      type: object
      properties:
        units:
          $ref: '#/components/schemas/carbohydrateratiounits.v1'
        recommendedBounds:
          $ref: '#/components/schemas/recommendedbounds.v1'
        absoluteBounds:
          $ref: '#/components/schemas/absolutebounds.v1'
        maxSegments:
          $ref: '#/components/schemas/maxsegments.v1'
    basalratemaximumguardrail.v1:
      title: Basal Rate Maximum Guard Rail
      description: Guard rail for the maximum basal rate setting
      type: object
      properties:
        units:
          $ref: '#/components/schemas/basalrateunits.v1'
        defaultValue:
          description: >-
            Default value. May be `null` if the device has no default value for
            the setting.
          type: object
          nullable: true
          allOf:
            - $ref: '#/components/schemas/fixeddecimal.v1'
        absoluteBounds:
          $ref: '#/components/schemas/absolutebounds.v1'
    bolusunits.v1:
      title: Bolus Units
      description: Bolus amount units
      type: string
      enum:
        - Units
      default: Units
    bolusamountmaximumguardrail.v1:
      title: Bolus Amount Maximum Guard Rail
      description: Guard rail for the maximum bolus amount setting
      type: object
      properties:
        units:
          $ref: '#/components/schemas/bolusunits.v1'
        recommendedBounds:
          $ref: '#/components/schemas/recommendedbounds.v1'
        absoluteBounds:
          $ref: '#/components/schemas/absolutebounds.v1'
    correctionrangeguardrail.v1:
      title: Correction Range Guard Rail
      description: Guard rail for a correction range setting
      type: object
      properties:
        units:
          $ref: '#/components/schemas/bloodglucoseunits.v1'
        recommendedBounds:
          $ref: '#/components/schemas/recommendedbounds.v1'
        absoluteBounds:
          $ref: '#/components/schemas/absolutebounds.v1'
        maxSegments:
          $ref: '#/components/schemas/maxsegments.v1'
    guardrails.v1:
      title: Guard Rails
      description: Guard rails used to validate therapy settings for the device
      type: object
      properties:
        glucoseSafetyLimit:
          $ref: '#/components/schemas/glucosesafetylimitguardrail.v1'
        insulinSensitivity:
          $ref: '#/components/schemas/insulinsensitivityguardrail.v1'
        basalRates:
          $ref: '#/components/schemas/basalratesguardrail.v1'
        carbohydrateRatio:
          $ref: '#/components/schemas/carbohydrateratioguardrail.v1'
        basalRateMaximum:
          $ref: '#/components/schemas/basalratemaximumguardrail.v1'
        bolusAmountMaximum:
          $ref: '#/components/schemas/bolusamountmaximumguardrail.v1'
        correctionRange:
          $ref: '#/components/schemas/correctionrangeguardrail.v1'
        preprandialCorrectionRange:
          $ref: '#/components/schemas/correctionrangeguardrail.v1'
        workoutCorrectionRange:
          $ref: '#/components/schemas/correctionrangeguardrail.v1'
    pump.v1:
      title: Pump
      description: A Tidepool supported insulin pump
      type: object
      properties:
        id:
          $ref: '#/components/schemas/guid.v1'
        displayName:
          description: Device display name
          type: string
          example: Omnipod 5
        manufacturers:
          description: Device manufacturers
          type: array
          items:
            type: string
          example:
            - Insulet
        model:
          description: Device model
          type: string
          example: Omnipod 5
        guardRails:
          $ref: '#/components/schemas/guardrails.v1'
    pumplist.v1:
      title: List Pumps Response
      description: List of Tidepool supported insulin pumps
      type: object
      properties:
        pumps:
          type: array
          items:
            $ref: '#/components/schemas/pump.v1'
    error.v1:
      title: Devices Error
      description: Error returned by the Devices API, in the gRPC-Gateway error format.
      type: object
      properties:
        code:
          description: >-
            [gRPC status code](https://grpc.io/docs/guides/status-codes/) (e.g.
            `5` for `NOT_FOUND`)
          type: integer
          format: int32
          example: 5
        message:
          description: Human readable error message
          type: string
          example: pump not found
        details:
          description: Additional error details
          type: array
          items:
            type: object
      required:
        - code
        - message
    cgm.v1:
      title: CGM
      description: A Tidepool supported continuous glucose monitor
      type: object
      properties:
        id:
          $ref: '#/components/schemas/guid.v1'
        displayName:
          description: Device display name
          type: string
          example: Dexcom G6
        manufacturers:
          description: Device manufacturers
          type: array
          items:
            type: string
          example:
            - Dexcom
        model:
          description: Device model
          type: string
          example: G6
    cgmlist.v1:
      title: List CGMs Response
      description: List of Tidepool supported continuous glucose monitors
      type: object
      properties:
        cgms:
          type: array
          items:
            $ref: '#/components/schemas/cgm.v1'
  parameters:
    deviceid.v1:
      description: Device ID
      name: id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/guid.v1'
