openapi: 3.0.1
info:
  title: Zus Health 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: Auth
    description: OAuth2 token issuance and exchange.
  - name: Patient
    description: FHIR R4 Patient resources.
  - name: FHIR
    description: General FHIR R4 resources.
  - name: Patient History
    description: Jobs that retrieve external data into the Zus Aggregated Profile.
  - name: Documents
    description: DocumentReference and Binary resources.
paths:
  /oauth/token:
    servers:
      - url: https://auth.zusapi.com
        description: Production auth
      - url: https://auth.sandbox.zusapi.com
        description: Sandbox auth
    post:
      operationId: createToken
      tags:
        - Auth
      summary: Issue or exchange an OAuth2 access token.
      description: >-
        Exchange credentials for a Zus access token. Supports the
        authorization_code (with PKCE) grant and the RFC 8693 token-exchange
        grant (grant_type urn:ietf:params:oauth:grant-type:token-exchange) for
        exchanging a third-party IdP ID token. Access tokens are valid for one
        hour (expires_in 3600). The token endpoint is rate limited to 200
        requests per hour per App Client.
      security: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TokenRequest'
      responses:
        '200':
          description: Access token issued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          description: Invalid credentials.
  /fhir/Patient:
    get:
      operationId: searchPatients
      tags:
        - Patient
      summary: Search Patient resources.
      description: >-
        Search FHIR R4 Patient resources. Supports search parameters including
        identifier, name, and the Zus universal patient identifier (upid).
        Returns a FHIR searchset Bundle. Default page size is 10 and can be
        expanded up to 500.
      parameters:
        - name: identifier
          in: query
          schema:
            type: string
          description: Token search on a Patient identifier (system|value).
        - name: name
          in: query
          schema:
            type: string
        - name: upid
          in: query
          schema:
            type: string
          description: Zus universal patient identifier.
        - name: _count
          in: query
          schema:
            type: integer
            default: 10
            maximum: 500
      responses:
        '200':
          description: A FHIR searchset Bundle.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
    post:
      operationId: createPatient
      tags:
        - Patient
      summary: Create a Patient resource.
      description: >-
        Create a FHIR R4 Patient. Setting Patient.active to true is the primary
        signal of an active treatment relationship and authorizes access to the
        patient's aggregated third-party data. Zus interprets a NULL value for
        Patient.active as false.
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '201':
          description: Patient created.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
  /fhir/Patient/{id}:
    get:
      operationId: readPatient
      tags:
        - Patient
      summary: Read a Patient by id.
      parameters:
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested Patient resource.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
        '404':
          description: Patient not found.
    put:
      operationId: updatePatient
      tags:
        - Patient
      summary: Replace a Patient by id.
      description: >-
        Replace an existing Patient. Version-aware writes are supported via the
        Zus-If-Match header.
      parameters:
        - $ref: '#/components/parameters/ResourceId'
        - name: Zus-If-Match
          in: header
          schema:
            type: string
          description: Version-aware write precondition.
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Patient'
      responses:
        '200':
          description: Patient updated.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Patient'
  /fhir/{resourceType}:
    get:
      operationId: searchResources
      tags:
        - FHIR
      summary: Search resources of a given FHIR R4 type.
      description: >-
        Search any supported FHIR R4 resource type (140+ types including
        Observation, Condition, Encounter, MedicationStatement, Procedure,
        DiagnosticReport, DocumentReference, and Binary). Returns a searchset
        Bundle.
      parameters:
        - name: resourceType
          in: path
          required: true
          schema:
            type: string
          example: Observation
        - name: patient
          in: query
          schema:
            type: string
        - name: _count
          in: query
          schema:
            type: integer
            default: 10
            maximum: 500
      responses:
        '200':
          description: A FHIR searchset Bundle.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
    post:
      operationId: createResource
      tags:
        - FHIR
      summary: Create a resource of a given FHIR R4 type.
      parameters:
        - name: resourceType
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Resource'
      responses:
        '201':
          description: Resource created.
  /fhir/{resourceType}/{id}:
    get:
      operationId: readResource
      tags:
        - FHIR
      summary: Read a resource by type and id.
      parameters:
        - name: resourceType
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: The requested resource.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Resource'
        '404':
          description: Resource not found.
    delete:
      operationId: deleteResource
      tags:
        - FHIR
      summary: Delete a resource by type and id.
      parameters:
        - name: resourceType
          in: path
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          description: Resource deleted.
  /fhir:
    post:
      operationId: submitBundle
      tags:
        - FHIR
      summary: Submit a FHIR transaction or batch Bundle.
      description: >-
        Submit a FHIR R4 transaction or batch Bundle (up to 100 entries).
        Supports conditional create, update, and delete by identifier.
      requestBody:
        required: true
        content:
          application/fhir+json:
            schema:
              $ref: '#/components/schemas/Bundle'
      responses:
        '200':
          description: A transaction-response or batch-response Bundle.
          content:
            application/fhir+json:
              schema:
                $ref: '#/components/schemas/Bundle'
  /patient-history/jobs:
    post:
      operationId: createPatientHistoryJob
      tags:
        - Patient History
      summary: Create a Patient History job.
      description: >-
        Submit a Patient History job to retrieve a patient's clinical data from
        Zus network partners into the FHIR Store, populating the Zus Aggregated
        Profile (ZAP). Submitting a Patient History request sets Patient.active
        to true for the patient.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatientHistoryJobRequest'
      responses:
        '201':
          description: Job created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientHistoryJob'
    get:
      operationId: listPatientHistoryJobs
      tags:
        - Patient History
      summary: List Patient History jobs.
      responses:
        '200':
          description: A list of Patient History jobs.
  /patient-history/jobs/{jobId}:
    get:
      operationId: getPatientHistoryJob
      tags:
        - Patient History
      summary: Retrieve a Patient History job.
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested Patient History job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientHistoryJob'
  /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:
  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>.
  parameters:
    ResourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: The logical id of the resource.
  schemas:
    TokenRequest:
      type: object
      required:
        - grant_type
      properties:
        grant_type:
          type: string
          description: >-
            authorization_code or
            urn:ietf:params:oauth:grant-type:token-exchange.
        client_id:
          type: string
        code:
          type: string
        code_verifier:
          type: string
        redirect_uri:
          type: string
        subject_token:
          type: string
          description: Third-party IdP ID token (token-exchange grant).
        subject_token_type:
          type: string
        scope:
          type: string
          example: openid profile email
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 3600
        scope:
          type: string
    PatientHistoryJobRequest:
      type: object
      properties:
        patient:
          type: object
          description: Reference to the FHIR Patient the job is run for.
        practitioner:
          type: object
          description: Reference to the requesting Practitioner.
        config:
          type: object
          description: Job configuration options.
    PatientHistoryJob:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          example: running
        patient:
          type: object
    Resource:
      type: object
      description: A generic FHIR R4 resource.
      properties:
        resourceType:
          type: string
        id:
          type: string
      additionalProperties: true
    Patient:
      type: object
      properties:
        resourceType:
          type: string
          example: Patient
        id:
          type: string
        active:
          type: boolean
          description: >-
            Primary signal of an active treatment relationship. Zus interprets
            NULL as false.
        identifier:
          type: array
          items:
            type: object
        name:
          type: array
          items:
            type: object
        gender:
          type: string
          description: administrative-gender; value set strictly enforced.
        birthDate:
          type: string
          format: date
      additionalProperties: true
    Bundle:
      type: object
      properties:
        resourceType:
          type: string
          example: Bundle
        type:
          type: string
          example: searchset
        total:
          type: integer
        entry:
          type: array
          items:
            type: object
      additionalProperties: true