{
  "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.\n\nFor 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"
        }
      }
    }
  }
}