openapi: 3.0.0
info:
  title: Metadata 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.
  contact:
    name: API Support
    url: https://support.tidepool.org/
    email: support@tidepool.org
  license:
    name: BSD-2-Clause
    url: https://github.com/tidepool-org/seagull/blob/master/LICENSE
  x-tidepool-service: https://github.com/tidepool-org/seagull
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: Metadata
    description: Create and update user metadata.
paths:
  /metadata/collections:
    get:
      operationId: GetMetadataCollections
      summary: Get Metadata Collections
      description: Returns list of valid metadata collections.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collectionnames.v1'
      security:
        - sessionToken: []
      tags:
        - Metadata
  /metadata/{userId}/{collectionName}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
      - $ref: '#/components/parameters/collectionname.v1'
    get:
      operationId: GetUserMetadataCollection
      summary: Get User Metadata Collection
      description: >-
        Returns the user's metadata collection corresponding to
        `collectionName`. Each metadata collection is an unbounded JSON object
        with client-defined fields.
      responses:
        '200':
          $ref: '#/components/responses/MetadataCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - sessionToken: []
      tags:
        - Metadata
    post:
      operationId: UpdateUserMetadataCollectionPost
      summary: Update User Metadata Collection
      description: >-
        Updates the user's metadata collection corresponding to
        `collectionName`. Each metadata collection is an unbounded JSON object
        with client-defined fields.
      requestBody:
        $ref: '#/components/requestBodies/MetadataCollection'
      responses:
        '200':
          $ref: '#/components/responses/MetadataCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - sessionToken: []
      tags:
        - Metadata
    put:
      operationId: UpdateUserMetadataCollectionPut
      summary: Update User Metadata Collection
      description: >-
        Updates the user's metadata collection corresponding to
        `collectionName`. Each metadata collection is an unbounded JSON object
        with client-defined fields.
      requestBody:
        $ref: '#/components/requestBodies/MetadataCollection'
      responses:
        '200':
          $ref: '#/components/responses/MetadataCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - sessionToken: []
      tags:
        - Metadata
  /metadata/{userId}/private/{fieldName}:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
      - $ref: '#/components/parameters/fieldname.v1'
    get:
      operationId: GetUserPrivateMetadataItem
      summary: Get User's Private Metadata Item
      description: Returns the named item from the user's private metadata collection.
      responses:
        '200':
          description: ''
      security:
        - serverToken: []
      tags:
        - Metadata
        - Internal
  /metadata/users/{userId}/users:
    parameters:
      - $ref: '#/components/parameters/tidepooluserid'
    get:
      operationId: ListUsers
      summary: List Users
      description: >-
        List all users who have trustee or trustor access to the user account
        identified by `userId`.
      responses:
        '200':
          $ref: '#/components/responses/TrustUsers'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      tags:
        - Metadata
      security:
        - sessionToken: []
components:
  securitySchemes:
    sessionToken:
      description: Tidepool Session Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
    serverToken:
      description: Tidepool Server Token
      type: apiKey
      name: X-Tidepool-Session-Token
      in: header
  requestBodies:
    MetadataCollection:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/collection.v1'
  responses:
    MetadataCollection:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/collection.v1'
    TrustUsers:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/trustusers.v1'
    Unauthorized:
      description: Unauthorized
    NotFound:
      description: Not Found
  schemas:
    collectionname.v1:
      title: Metadata Collection Name
      type: string
      enum:
        - profile
        - preferences
        - settings
        - groups
        - private
      example: profile
    collectionnames.v1:
      title: Metadata Collection Names
      type: array
      items:
        $ref: '#/components/schemas/collectionname.v1'
      example:
        - profile
        - groups
        - private
    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
    fullname.v1:
      title: Full Name
      type: string
      example: James Jellyfish
    diagnosistype.v1:
      title: Diagnosis Type
      type: string
      enum:
        - type1
        - type2
        - gestational
        - prediabetes
        - lada
        - mody
        - other
      example: type1
    diagnosisdate.v1:
      title: Diagnosis Date
      type: string
      format: date
      pattern: ^\d{4}-\d{2}-\d{2}$
      example: '2013-05-09'
      x-go-type: string
    birthday.v1:
      title: Birthday
      type: string
      format: date
      example: '2012-08-30'
      x-go-type: string
    biologicalsex.v1:
      title: Biological Sex
      type: string
      enum:
        - male
        - female
      example: male
    targetdevices.v1:
      title: Target Devices
      type: array
      items:
        type: string
        example: bayercontournext
    targettimezone.v1:
      title: Target Time Zone
      type: string
      example: US/Eastern
    about.v1:
      title: About Me
      type: string
      example: Jellyman is awesome!
    userprofile.v1:
      title: User Profile
      description: User profile used by Tidepool Web
      type: object
      properties:
        fullName:
          $ref: '#/components/schemas/fullname.v1'
        patient:
          type: object
          properties:
            diagnosisType:
              $ref: '#/components/schemas/diagnosistype.v1'
            diagnosisDate:
              $ref: '#/components/schemas/diagnosisdate.v1'
            birthday:
              $ref: '#/components/schemas/birthday.v1'
            biologicalSex:
              $ref: '#/components/schemas/biologicalsex.v1'
            targetDevices:
              $ref: '#/components/schemas/targetdevices.v1'
            targetTimezone:
              $ref: '#/components/schemas/targettimezone.v1'
            about:
              $ref: '#/components/schemas/about.v1'
    clinicname.v1:
      title: Clinic Name
      type: string
      example: ACME Endocrinology
    clinicianrole.v1:
      type: string
      enum:
        - clinic_manager
        - diabetes_educator
        - endocrinologist
        - front_desk
        - information_technology
        - medical_assistant
        - nurse
        - primary_care_physician
        - physician_assistant
        - other
      example: clinic_manager
    phonenumber.v1:
      title: Phone Number
      type: string
      example: +1 (800) 555-1212
    clinicianprofile.v1:
      title: Clinician Profile
      description: Clinician profile used by Tidepool Web
      type: object
      properties:
        fullName:
          $ref: '#/components/schemas/fullname.v1'
        clinic:
          type: object
          properties:
            name:
              $ref: '#/components/schemas/clinicname.v1'
            role:
              $ref: '#/components/schemas/clinicianrole.v1'
            telephone:
              $ref: '#/components/schemas/phonenumber.v1'
    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
    mrn.v1:
      title: Medical Record Number (MRN)
      type: string
      example: '123456'
    emailaddresses.v1:
      title: User Email Addresses
      type: array
      uniqueItems: true
      items:
        $ref: '#/components/schemas/emailaddress.v1'
      minItems: 1
    patientprofile.v1:
      title: Patient Profile
      description: Patient profile used by Tidepool Web
      type: object
      properties:
        fullName:
          $ref: '#/components/schemas/fullname.v1'
        patient:
          type: object
          properties:
            birthday:
              $ref: '#/components/schemas/birthday.v1'
            email:
              $ref: '#/components/schemas/emailaddress.v1'
            mrn:
              $ref: '#/components/schemas/mrn.v1'
            targetDevices:
              $ref: '#/components/schemas/targetdevices.v1'
            targetTimezone:
              $ref: '#/components/schemas/targettimezone.v1'
        emails:
          $ref: '#/components/schemas/emailaddresses.v1'
    profile.v1:
      title: Profile
      description: Profiles used by Tidepool Web
      type: object
      anyOf:
        - $ref: '#/components/schemas/userprofile.v1'
        - $ref: '#/components/schemas/clinicianprofile.v1'
        - $ref: '#/components/schemas/patientprofile.v1'
    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
    preferences.v1:
      title: User Preferences
      description: User preferences collection used by Tidepool Web
      type: object
      properties:
        dismissedDexcomConnectBannerTime:
          $ref: '#/components/schemas/datetime.v1'
      additionalProperties: true
    settings.v1:
      title: User Settings
      description: User settings used by Tidepool Web
      type: object
      properties:
        bgTarget:
          type: object
          properties:
            low:
              type: number
              example: 65
            high:
              type: number
              example: 180
    private.v1:
      title: Private Collection
      description: Private collection used by Tidepool Platform
      type: object
      properties:
        uploads:
          type: object
          properties:
            name:
              type: string
              example: ''
            id:
              $ref: '#/components/schemas/tidepooluserid'
            hash:
              type: string
              example: 27dc848b6ca43eb92add9d4d
    collection.v1:
      title: Metadata Collection
      type: object
      anyOf:
        - $ref: '#/components/schemas/profile.v1'
        - $ref: '#/components/schemas/preferences.v1'
        - $ref: '#/components/schemas/settings.v1'
        - $ref: '#/components/schemas/private.v1'
    emailverified.v1:
      title: User Email Verification Status
      description: >-
        `true` if the user has verified their email address. `false` or not
        present if the user has not verified their email address.
      type: boolean
      example: true
    role.v1:
      title: User Role
      type: string
      enum:
        - clinic
      example: clinic
    roles.v1:
      title: User Roles
      type: array
      uniqueItems: true
      items:
        $ref: '#/components/schemas/role.v1'
      minItems: 0
    user.v1:
      title: User
      type: object
      properties:
        emailVerified:
          $ref: '#/components/schemas/emailverified.v1'
        emails:
          $ref: '#/components/schemas/emailaddresses.v1'
        termsAccepted:
          $ref: '#/components/schemas/datetime.v1'
        roles:
          $ref: '#/components/schemas/roles.v1'
        userid:
          $ref: '#/components/schemas/tidepooluserid'
        username:
          $ref: '#/components/schemas/emailaddress.v1'
        profile:
          $ref: '#/components/schemas/profile.v1'
      required:
        - userid
    permission.v1:
      title: Permission
      description: >-
        The presence of this object indicates that the user has been granted the
        named permission.
      type: object
      example: {}
    owner.v1:
      title: Owner
      description: Full account owner access permission.
      type: object
      properties:
        root:
          $ref: '#/components/schemas/permission.v1'
      example:
        root: {}
    custodian.v1:
      title: Custodian
      description: Full custodial permission.
      type: object
      properties:
        custodian:
          $ref: '#/components/schemas/permission.v1'
      example:
        custodian: {}
    view.v1:
      title: View
      description: Permission to view diabetes data in the account.
      type: object
      properties:
        view:
          $ref: '#/components/schemas/permission.v1'
      example:
        view: {}
    note.v1:
      title: Notes
      description: Permission to view and manage notes in the account.
      type: object
      properties:
        note:
          $ref: '#/components/schemas/permission.v1'
      example:
        note: {}
    upload.v1:
      title: Upload
      description: Permission to upload diabetes data to the account.
      type: object
      properties:
        upload:
          $ref: '#/components/schemas/permission.v1'
      example:
        upload: {}
    userpermissions.v1:
      title: User Permissions
      description: Access permissions granted to a single user.
      type: object
      anyOf:
        - $ref: '#/components/schemas/owner.v1'
        - $ref: '#/components/schemas/custodian.v1'
        - $ref: '#/components/schemas/view.v1'
        - $ref: '#/components/schemas/note.v1'
        - $ref: '#/components/schemas/upload.v1'
      minProperties: 1
      example:
        note: {}
        upload: {}
        view: {}
    trusteeuser.v1:
      title: Trustee User
      type: object
      allOf:
        - $ref: '#/components/schemas/user.v1'
        - type: object
          properties:
            trusteePermissions:
              $ref: '#/components/schemas/userpermissions.v1'
      required:
        - trusteePermissions
    trustoruser.v1:
      title: Trustor User
      type: object
      allOf:
        - $ref: '#/components/schemas/user.v1'
        - type: object
          properties:
            trustorPermissions:
              $ref: '#/components/schemas/userpermissions.v1'
      required:
        - trustorPermissions
    trustusers.v1:
      title: Trustee and Trustor Users
      type: array
      items:
        anyOf:
          - $ref: '#/components/schemas/trusteeuser.v1'
          - $ref: '#/components/schemas/trustoruser.v1'
  parameters:
    tidepooluserid:
      description: Tidepool User ID
      name: userId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/tidepooluserid'
    collectionname.v1:
      description: Metadata Collection Name
      name: collectionName
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/collectionname.v1'
    fieldname.v1:
      description: Metadata Field Name
      name: fieldName
      in: path
      required: true
      schema:
        type: string
