openapi: 3.0.0
info:
  title: Prescriptions API
  version: '1.0'
  description: Prescription service for Tidepool Loop
  contact:
    url: https://support.tidepool.org/
    name: API Support
    email: support@tidepool.org
  termsOfService: https://developer.tidepool.org/terms-of-use/
  license:
    name: BSD 2-Clause "Simplified" License
    url: https://github.com/tidepool-org/platform/master/LICENSE
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
tags:
  - name: Internal
    description: APIs intended for internal use by Tidepool.
  - name: Prescriptions
    description: Manage prescriptions for Tidepool Loop
paths:
  /v1/clinics/{clinicId}/prescriptions:
    get:
      summary: List Prescriptions
      security:
        - sessionToken: []
      tags:
        - Prescriptions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/prescription.v1'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
      operationId: ListClinicPrescriptions
      description: Retrieve the list of prescriptions created by clinic members
      parameters:
        - schema:
            type: string
          in: query
          name: id
        - schema:
            type: string
          in: query
          name: patientUserId
        - schema:
            type: string
            format: email
          in: query
          name: patientEmail
        - schema:
            type: string
          in: query
          name: state
        - schema:
            type: string
            format: date-time
          in: query
          name: createdAfter
          description: inclusive
        - schema:
            type: string
            format: date-time
          in: query
          name: createdBefore
          description: exclusive
        - schema:
            type: string
            format: date-time
          in: query
          name: modifiedAfter
          description: inclusive
        - schema:
            type: string
            format: date-time
          in: query
          name: modifiedBefore
          description: exclusive
    post:
      summary: Create a Prescription
      operationId: CreatePrescription
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/prescription.v1'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
      description: Create a new prescription
      tags:
        - Prescriptions
      security:
        - sessionToken: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/writableattributes.v1'
    parameters:
      - schema:
          type: string
        name: clinicId
        in: path
        required: true
  /v1/clinics/{clinicId}/prescriptions/{prescriptionId}:
    parameters:
      - schema:
          type: string
        name: prescriptionId
        in: path
        required: true
        description: ''
      - schema:
          type: string
        name: clinicId
        in: path
        required: true
    get:
      summary: Get Prescription
      tags:
        - Prescriptions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/prescription.v1'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
      operationId: GetPrescriptionById
      description: Retrieve a prescription by id
      security:
        - sessionToken: []
    delete:
      summary: Delete Prescription
      operationId: DeletePrescription
      responses:
        '200':
          description: OK
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
      description: >-
        Clinician only endpoint to delete a prescription. Works only when the
        prescription has status `draft`.
      security:
        - sessionToken: []
      tags:
        - Prescriptions
  /v1/clinics/{clinicId}/prescriptions/{prescriptionId}/revisions:
    parameters:
      - schema:
          type: string
        name: prescriptionId
        in: path
        required: true
      - schema:
          type: string
        name: clinicId
        in: path
        required: true
    post:
      summary: Create new revision
      operationId: CreatePrescriptionRevision
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/revision.v1'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
      description: Add a new revision to a prescription which is still a draft.
      security:
        - sessionToken: []
      tags:
        - Prescriptions
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/writableattributes.v1'
        description: ''
  /v1/patients/{userId}/prescriptions:
    post:
      summary: Claim Prescription
      operationId: ClaimPrescription
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/prescription.v1'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errorresponse.v1'
      security:
        - sessionToken: []
      tags:
        - Prescriptions
      description: Claim a submitted prescription using an access code and date of birth.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/claim.req.v1'
    parameters:
      - schema:
          type: string
        name: userId
        in: path
        required: true
    get:
      summary: List Prescriptions for Patient
      operationId: ListPatientPrescriptions
      responses:
        '200':
          description: OK
      description: Retrieve a list of prescription that the user has claimed
      security:
        - sessionToken: []
      tags:
        - Prescriptions
  /v1/patients/{userId}/prescriptions/{prescriptionId}:
    parameters:
      - schema:
          type: string
        name: userId
        in: path
        required: true
      - schema:
          type: string
        name: prescriptionId
        in: path
        required: true
    get:
      summary: Get Prescription for User
      tags:
        - Prescriptions
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/prescription.v1'
      operationId: GetPrescriptionForUser
      description: Retrieve a prescription by id
      security:
        - sessionToken: []
    patch:
      summary: Update Prescription State
      operationId: UpdatePrescriptionState
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/prescription.v1'
      description: Update prescription state
      tags:
        - Prescriptions
      security:
        - sessionToken: []
components:
  schemas:
    objectid.v1:
      title: Object Id
      type: string
      description: String representation of a resource id
      minLength: 24
      maxLength: 24
      pattern: ^[a-f0-9]{24}$
      readOnly: true
    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
    state.v1:
      type: string
      title: Prescriptions State
      enum:
        - draft
        - pending
        - submitted
        - claimed
        - active
        - inactive
        - expired
      x-tags:
        - prescription
    datetime.v1:
      title: Date/Time
      description: >-
        [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) / [ISO
        8601](https://www.iso.org/iso-8601-date-and-time-format.html) timestamp
        _with_ timezone information
      type: string
      format: date-time
      example: '2017-02-06T02:37:46Z'
      x-go-type: string
    birthday.v1:
      title: Birthday
      type: string
      format: date
      example: '2012-08-30'
      x-go-type: string
    emailaddress.v1:
      title: Email Address
      description: >-
        An email address, as specified by [RFC
        5322](https://datatracker.ietf.org/doc/html/rfc5322).
      type: string
      format: email
      minLength: 6
      example: example@tidepool.org
      x-go-type: string
    weight.v1:
      title: Weight
      type: object
      properties:
        value:
          type: number
          minimum: 0
          exclusiveMinimum: true
        units:
          type: string
      required:
        - value
        - units
      x-tags:
        - prescription
    phone.v1:
      title: Phone Number
      type: object
      properties:
        countryCode:
          type: string
        number:
          type: string
      required:
        - countryCode
        - number
      x-tags:
        - prescription
    unitsmgdl.v1:
      title: Blood Unit (mg/dL)
      type: string
      enum:
        - mg/dL
        - mg/dl
      example: mg/dL
      x-tags:
        - Data
    unitsmmol.v1:
      title: Blood Unit (mmol/L)
      type: string
      enum:
        - mmol/L
        - mmol/l
      example: mmol/L
      x-tags:
        - Data
    units.v1:
      title: Blood Unit (mg/dL or mmol/L)
      oneOf:
        - $ref: '#/components/schemas/unitsmgdl.v1'
        - $ref: '#/components/schemas/unitsmmol.v1'
      x-tags:
        - Data
    startarray.v1:
      title: Basal Rate Start Array
      description: >-
        A set of key-value pairs encoding the PWD's programmed basal schedules,
        where each key is a basal schedule name and each value is an array of
        basal schedule segment objects.
      type: array
      items:
        type: object
        properties:
          rate:
            type: number
            description: >-
              A floating point number >= 0 representing the amount of insulin
              delivered in Units per hour.
            format: float
            minimum: 0
            maximum: 20
          start:
            type: integer
            format: int64
            description: Integer value representing milliseconds since midnight.
            minimum: 0
            maximum: 86400000
            exclusiveMaximum: true
        required:
          - rate
          - start
      x-tags:
        - Data
    targetmgdl.v1:
      title: Blood Glucose Target Value (mg/dL)
      description: Blood glucose target values, in `mg/dL`
      type: object
      properties:
        high:
          type: number
          minimum: 0
          maximum: 1000
          description: |-
            An integer encoding the upper bound of a PWD's blood glucose target.

            The minimum value should be >= `low` or `target`, whichever present
        low:
          type: number
          minimum: 0
          maximum: 1000
          description: An integer encoding the lower bound of a PWD's blood glucose target.
        range:
          type: number
          minimum: 0
          maximum: 1000
          description: >-
            An integer encoding the allowed deviation above or below the PWD's
            target blood glucose.


            Maximum should be min(`target`, 1000 - `target`) such that
            `target`-`range` >= 0 and `target`+`range` <= 1000
        target:
          type: number
          minimum: 0
          maximum: 1000
          description: >-
            An integer encoding the PWD's target blood glucose as a single
            value.
      example:
        high: 180
        low: 80
      x-tags:
        - Data
    targetmmol.v1:
      title: Blood Glucose Target Value (mmol/L)
      description: Blood glucose target values, in `mmol/L`
      type: object
      properties:
        high:
          type: number
          description: |-
            An integer encoding the upper bound of a PWD's blood glucose target.

            The minimum value should be >= `low` or `target`, whichever present
          minimum: 0
          maximum: 55
        low:
          type: number
          minimum: 0
          maximum: 55
          description: An integer encoding the lower bound of a PWD's blood glucose target.
        range:
          type: number
          minimum: 0
          maximum: 55
          description: >-
            An integer encoding the allowed deviation above or below the PWD's
            target blood glucose.


            Maximum should be min(`target`, 1000 - `target`) such that
            `target`-`range` >= 0 and `target`+`range` <= 1000
        target:
          type: number
          minimum: 0
          maximum: 55
          description: >-
            An integer encoding the PWD's target blood glucose as a single
            value.
      x-tags:
        - Data
    target.v1:
      title: Blood Glucose Target
      oneOf:
        - $ref: '#/components/schemas/targetmgdl.v1'
        - $ref: '#/components/schemas/targetmmol.v1'
      x-tags:
        - Data
    start.v1:
      title: Start Time
      description: Start time as millisecond offset from midnight
      type: object
      properties:
        start:
          type: number
          minimum: 0
          maximum: 86400000
      required:
        - start
      x-tags:
        - Data
    targetstart.v1:
      title: Blood Glucose Target Start
      description: ''
      allOf:
        - $ref: '#/components/schemas/target.v1'
        - $ref: '#/components/schemas/start.v1'
      x-tags:
        - Data
    ratio.v1:
      title: Carbohydrate Ratio
      type: object
      properties:
        amount:
          type: number
          minimum: 0
          maximum: 250
      required:
        - amount
      x-tags:
        - Data
    ratiostart.v1:
      title: Carbohydrate Ratio Start
      allOf:
        - $ref: '#/components/schemas/start.v1'
        - $ref: '#/components/schemas/ratio.v1'
      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
    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
    value.v1:
      title: Blood Value (in mg/dL or mmol/L units)
      oneOf:
        - $ref: '#/components/schemas/valuemgdl.v1'
        - $ref: '#/components/schemas/valuemmol.v1'
      x-tags:
        - Data
    sensitivitystart.v1:
      title: Insulin Sensitivity Start
      allOf:
        - type: object
          properties:
            amount:
              $ref: '#/components/schemas/value.v1'
        - $ref: '#/components/schemas/start.v1'
      x-tags:
        - Data
    maximum.v1:
      title: Basal Rate Maximum
      type: object
      properties:
        units:
          type: string
          enum:
            - Units/hour
        value:
          type: number
          minimum: 0
          maximum: 100
      required:
        - units
        - value
      x-tags:
        - Data
    amountmaximum.v1:
      title: Bolus Amount Maximum
      type: object
      properties:
        units:
          type: string
          enum:
            - Units
        value:
          type: number
          minimum: 0
          maximum: 100
      required:
        - units
        - value
      x-tags:
        - Data
    suspendthreshold.v1:
      title: Suspend Threshold
      description: ''
      type: object
      properties:
        units:
          $ref: '#/components/schemas/units.v1'
        value:
          $ref: '#/components/schemas/value.v1'
      required:
        - units
        - value
      x-tags:
        - Data
    model.v1:
      title: Insulin Model
      description: ''
      type: string
      enum:
        - rapidChild
        - rapidAdult
      example: rapidAdult
      x-tags:
        - Data
    settings.v1:
      title: Pump Settings
      type: object
      x-tags:
        - prescription
      properties:
        bloodGlucoseUnits:
          $ref: '#/components/schemas/units.v1'
        basalRateSchedule:
          $ref: '#/components/schemas/startarray.v1'
        bloodGlucoseTargetSchedule:
          type: array
          items:
            $ref: '#/components/schemas/targetstart.v1'
        carbohydrateRatioSchedule:
          type: array
          items:
            $ref: '#/components/schemas/ratiostart.v1'
        insulinSensitivitySchedule:
          type: array
          items:
            $ref: '#/components/schemas/sensitivitystart.v1'
        basalRateMaximum:
          $ref: '#/components/schemas/maximum.v1'
        bolusAmountMaximum:
          $ref: '#/components/schemas/amountmaximum.v1'
        bloodGlucoseSuspendThreshold:
          $ref: '#/components/schemas/suspendthreshold.v1'
        insulinModel:
          $ref: '#/components/schemas/model.v1'
        pumpId:
          type: string
          format: uuid
        cgmId:
          type: string
          format: uuid
        bloodGlucoseTargetPhysicalActivity:
          $ref: '#/components/schemas/target.v1'
        bloodGlucoseTargetPreprandial:
          $ref: '#/components/schemas/target.v1'
      required:
        - bloodGlucoseUnits
        - basalRateSchedule
        - bloodGlucoseTargetSchedule
        - carbohydrateRatioSchedule
        - insulinSensitivitySchedule
        - basalRateMaximum
        - bolusAmountMaximum
        - bloodGlucoseSuspendThreshold
        - insulinModel
        - pumpId
        - cgmId
    calculator.v1:
      title: calculator.v1
      type: object
      description: ''
      properties:
        method:
          type: string
          enum:
            - weight
            - totalDailyDose
            - totalDailyDoseAndWeight
        weight:
          type: number
          format: float
          minimum: 0
          description: Required if `method` is `weight` or `totalDailyDoseAndWeight`
          exclusiveMinimum: true
        weightUnits:
          type: string
          enum:
            - kg
            - lbs
          description: Required if `method` is `weight` or `totalDailyDoseAndWeight`
        totalDailyDoseScaleFactor:
          type: number
          minimum: 0
          maximum: 1
          description: >-
            Required if `method` is `totalDailyDose` or
            `totalDailyDoseAndWeight`.  At present, only options are `1` and
            `0.75`
          format: float
        totalDailyDose:
          type: number
          minimum: 0
          format: float
          description: >-
            Required if `method` is `totalDailyDose` or
            `totalDailyDoseAndWeight`
          exclusiveMinimum: true
        recommendedBasalRate:
          type: number
          minimum: 0
          format: float
          exclusiveMinimum: true
        recommendedInsulinSensitivity:
          type: number
          minimum: 0
          format: float
          exclusiveMinimum: true
        recommendedCarbohydrateRatio:
          type: number
          minimum: 0
          format: float
          exclusiveMinimum: true
      required:
        - method
        - recommendedBasalRate
        - recommendedInsulinSensitivity
        - recommendedCarbohydrateRatio
    writableattributes.v1:
      title: Revision Attributes
      type: object
      x-tags:
        - prescription
      properties:
        firstName:
          type: string
        lastName:
          type: string
        birthday:
          $ref: '#/components/schemas/birthday.v1'
        mrn:
          type: string
        email:
          $ref: '#/components/schemas/emailaddress.v1'
        sex:
          type: string
          enum:
            - male
            - female
            - undisclosed
        weight:
          $ref: '#/components/schemas/weight.v1'
        yearOfDiagnosis:
          type: integer
          format: int32
          minimum: 1900
        phoneNumber:
          $ref: '#/components/schemas/phone.v1'
        initialSettings:
          $ref: '#/components/schemas/settings.v1'
        training:
          type: string
          enum:
            - inPerson
            - inModule
        therapySettings:
          type: string
          enum:
            - initial
            - transferPumpSettings
        prescriberTermsAccepted:
          type: boolean
        state:
          $ref: '#/components/schemas/state.v1'
        calculator:
          $ref: '#/components/schemas/calculator.v1'
        revisionHash:
          type: string
          pattern: ^[A-Fa-f0-9]{64}$
          description: >-
            Canonicalized and SHA-512-encrypted hex output of the sent revision
            payload
        createdUserId:
          $ref: '#/components/schemas/tidepooluserid'
        caregiverFirstName:
          type: string
        caregiverLastName:
          type: string
        accountType:
          type: string
          enum:
            - patient
            - caregiver
      required:
        - state
        - revisionHash
    attributes.v1:
      allOf:
        - $ref: '#/components/schemas/writableattributes.v1'
        - type: object
          properties:
            createdTime:
              $ref: '#/components/schemas/datetime.v1'
      title: Revision Attributes
      x-tags:
        - prescription
    revision.v1:
      title: Prescription Revision
      type: object
      properties:
        revisionId:
          type: integer
          format: int32
        attributes:
          $ref: '#/components/schemas/attributes.v1'
      x-tags:
        - prescription
    clinicId.v1:
      title: Clinic ID
      description: Clinic identifier.
      type: string
      minLength: 24
      maxLength: 24
      pattern: ^[a-f0-9]{24}$
      readOnly: true
      example: 2fe2488217ee43e1b2e83c2f
    prescription.v1:
      title: Tidepool Loop Prescription
      type: object
      description: Object describing a Tidepool Loop Prescription
      properties:
        id:
          $ref: '#/components/schemas/objectid.v1'
        patientUserId:
          $ref: '#/components/schemas/tidepooluserid'
        state:
          $ref: '#/components/schemas/state.v1'
        expirationTime:
          $ref: '#/components/schemas/datetime.v1'
        prescriberUserId:
          $ref: '#/components/schemas/tidepooluserid'
        createdTime:
          $ref: '#/components/schemas/datetime.v1'
        createdUserId:
          $ref: '#/components/schemas/tidepooluserid'
        deletedTime:
          $ref: '#/components/schemas/datetime.v1'
        deletedUserId:
          $ref: '#/components/schemas/tidepooluserid'
        modifiedTime:
          $ref: '#/components/schemas/datetime.v1'
        modifiedUserId:
          $ref: '#/components/schemas/tidepooluserid'
        latestRevision:
          $ref: '#/components/schemas/revision.v1'
        clinicId:
          $ref: '#/components/schemas/clinicId.v1'
      required:
        - id
        - state
        - createdTime
        - createdUserId
        - modifiedTime
        - modifiedUserId
        - latestRevision
        - clinicId
    errorresponse.v1:
      title: ErrorResponse
      type: object
      properties:
        code:
          type: integer
          format: int32
          description: Error reason code
        reason:
          type: string
          description: Error reason text
    accesscode.v1:
      type: string
      title: Access Code
      minLength: 6
      maxLength: 6
      pattern: ^[A-HJ-NP-Z2-9]+$
      x-tags:
        - prescription
    claim.req.v1:
      title: Claim Prescription Request
      type: object
      properties:
        accessCode:
          $ref: '#/components/schemas/accesscode.v1'
        birthday:
          $ref: '#/components/schemas/birthday.v1'
      required:
        - accessCode
        - birthday
      x-tags:
        - prescription
  securitySchemes:
    sessionToken:
      description: Tidepool Session Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
  parameters: {}
