openapi: 3.0.1
info:
  title: Metriport Consolidated Document API
  description: Metriport is an open-source, universal API for healthcare data. The Medical API exchanges patient medical records across the CommonWell and Carequality networks and returns consolidated FHIR R4 data; the Devices API hydrates activity, biometrics, nutrition, and sleep data from connected wearables and mHealth apps. This specification documents the hosted Metriport cloud surface at https://api.metriport.com. The same code may be self-hosted from the open-source repository.
  termsOfService: https://www.metriport.com/terms
  contact:
    name: Metriport Support
    email: contact@metriport.com
    url: https://docs.metriport.com
  version: '1.0'
servers:
- url: https://api.metriport.com
  description: Metriport hosted production API
- url: https://api.sandbox.metriport.com
  description: Metriport sandbox API
security:
- ApiKeyAuth: []
tags:
- name: Document
  description: Medical API clinical document query and retrieval.
paths:
  /medical/v1/document/query:
    post:
      operationId: startDocumentQuery
      tags:
      - Document
      summary: Start Document Query
      description: Triggers a network query across the HIE networks to discover and download the available clinical documents for a Patient. Results are delivered asynchronously via webhook.
      parameters:
      - name: patientId
        in: query
        required: true
        schema:
          type: string
      - name: facilityId
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The document query progress object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentQuery'
    get:
      operationId: getDocumentQueryStatus
      tags:
      - Document
      summary: Get Document Query Status
      parameters:
      - name: patientId
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The current document query progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentQuery'
  /medical/v1/document:
    get:
      operationId: listDocuments
      tags:
      - Document
      summary: List Documents
      description: Lists the available clinical documents (FHIR DocumentReferences) for a Patient that have been retrieved from the networks.
      parameters:
      - name: patientId
        in: query
        required: true
        schema:
          type: string
      - name: dateFrom
        in: query
        required: false
        schema:
          type: string
          format: date
      - name: dateTo
        in: query
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: A list of DocumentReferences.
          content:
            application/json:
              schema:
                type: object
                properties:
                  documents:
                    type: array
                    items:
                      $ref: '#/components/schemas/DocumentReference'
  /medical/v1/document/download-url:
    get:
      operationId: getDocumentUrl
      tags:
      - Document
      summary: Get Document URL
      description: Returns a signed URL to download a specific document referenced by its file name.
      parameters:
      - name: fileName
        in: query
        required: true
        schema:
          type: string
      - name: conversionType
        in: query
        required: false
        schema:
          type: string
          enum:
          - html
          - pdf
      responses:
        '200':
          description: A signed download URL.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
components:
  schemas:
    DocumentQuery:
      type: object
      properties:
        download:
          $ref: '#/components/schemas/Progress'
        convert:
          $ref: '#/components/schemas/Progress'
    DocumentReference:
      type: object
      description: A FHIR R4 DocumentReference describing a retrieved clinical document.
      properties:
        id:
          type: string
        fileName:
          type: string
        description:
          type: string
        status:
          type: string
        contentType:
          type: string
        size:
          type: integer
        indexed:
          type: string
          format: date-time
    Progress:
      type: object
      properties:
        status:
          type: string
          enum:
          - processing
          - completed
          - failed
        total:
          type: integer
        successful:
          type: integer
        errors:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key