openapi: 3.0.1
info:
  title: Zus Health Auth Documents API
  description: FHIR R4 (v4.0.1) REST API for the Zus Health shared health-data platform. Provides access to Patient resources, the Zus Aggregated Profile (ZAP) via Patient History jobs, general FHIR resources, document ingestion and retrieval through DocumentReference and Binary, and OAuth2 token issuance. All requests are authenticated with an OAuth2 Bearer access token. Endpoints and behavior are derived from the public Zus documentation at https://docs.zushealth.com; production hostnames use api.zusapi.com and the sandbox uses api.sandbox.zusapi.com / auth.sandbox.zusapi.com.
  termsOfService: https://zushealth.com
  contact:
    name: Zus Health
    url: https://docs.zushealth.com
  version: '1.0'
servers:
- url: https://api.zusapi.com
  description: Production
- url: https://api.sandbox.zusapi.com
  description: Sandbox
security:
- bearerAuth: []
tags:
- name: Documents
  description: DocumentReference and Binary resources.
paths:
  /fhir/DocumentReference/{id}:
    get:
      operationId: readDocumentReference
      tags:
      - Documents
      summary: Read a DocumentReference by id.
      description: Retrieve a FHIR R4 DocumentReference. Narrative content (text.div) is treated as opaque and is not validated.
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested DocumentReference.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Resource'
  /fhir/Binary/{id}:
    get:
      operationId: readBinary
      tags:
      - Documents
      summary: Read a Binary resource by id.
      description: Retrieve a FHIR R4 Binary resource. The base64-encoded Binary.data payload is stored as submitted and is not run through instance validation.
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested Binary resource.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Resource'
components:
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The logical id of the resource.
  schemas:
    Resource:
      type: object
      description: A generic FHIR R4 resource.
      properties:
        resourceType:
          type: string
        id:
          type: string
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth2 Bearer access token obtained from the Zus token endpoint (auth.zusapi.com/oauth/token). Sent as Authorization: Bearer <ACCESS_TOKEN>.'