openapi: 3.0.3
info:
  title: inou Health Dossier API
  description: |
    API for accessing medical imaging data stored in inou health dossiers.
    
    ## Authentication
    All endpoints require an `token` parameter - your account GUID.
    
    ## Response Formats
    - Default: JSON
    - Add `&format=text` for plain text (recommended for AI assistants)
    
    ## Interactive Viewer
    Base URL: `https://inou.com/viewer/?token={token}`
    
    Deep linking:
    - Open specific study: `?token={token}&study={study_guid}`
    - Open specific series: `?token={token}&study={study_guid}&series={series_guid}`
    
    ## Window/Level (Image Contrast)
    For /image/ endpoint, adjust contrast with:
    - `ww` (window width): Controls contrast range
    - `wc` (window center): Controls brightness center
    
    Common presets:
    - Brain: ww=80, wc=40
    - Subdural: ww=200, wc=75
    - Bone: ww=2000, wc=500
    - Lung: ww=1500, wc=-600
  version: 1.0.0
  contact:
    name: inou
    url: https://inou.com

servers:
  - url: https://inou.com
    description: Production

paths:
  /api/dossiers:
    get:
      summary: List dossiers
      description: List all patient dossiers accessible to this account (your own + shared with you).
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: Your authentication token (dossier GUID)
        - name: format
          in: query
          schema:
            type: string
            enum: [text]
          description: Set to "text" for plain text output
      responses:
        '200':
          description: List of dossiers
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                    name:
                      type: string

  /api/studies:
    get:
      summary: List imaging studies
      description: List all imaging studies in a dossier.
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: dossier_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: Dossier GUID
        - name: format
          in: query
          schema:
            type: string
            enum: [text]
      responses:
        '200':
          description: List of studies
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                    patient_name:
                      type: string
                    study_date:
                      type: string
                    study_desc:
                      type: string
                    series_count:
                      type: integer

  /api/series:
    get:
      summary: List series in a study
      description: List all series for a study. Filter by description (AX, T1, FLAIR, SAG, COR, etc).
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: dossier_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: study_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: filter
          in: query
          schema:
            type: string
          description: Filter by series description (e.g., "T1", "FLAIR", "SAG")
        - name: format
          in: query
          schema:
            type: string
            enum: [text]
      responses:
        '200':
          description: List of series

  /api/slices:
    get:
      summary: List slices in a series
      description: List all slices with position data (mm coordinates, orientation, pixel spacing).
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: dossier_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: series_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: format
          in: query
          schema:
            type: string
            enum: [text]
      responses:
        '200':
          description: List of slices with position info


  /image/{slice_guid}:
    get:
      summary: Get slice image
      description: Fetch a slice as PNG image. Adjust window/level for contrast.
      parameters:
        - name: slice_guid
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: dossier_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: ww
          in: query
          schema:
            type: number
          description: Window width (contrast range). Brain=80, Bone=2000, Lung=1500
        - name: wc
          in: query
          schema:
            type: number
          description: Window center (brightness). Brain=40, Bone=500, Lung=-600
      responses:
        '200':
          description: PNG image
          content:
            image/png:
              schema:
                type: string
                format: binary

  /viewer/:
    get:
      summary: Interactive DICOM viewer
      description: Open the web-based DICOM viewer with 3D crosshair navigation.
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
          description: Dossier GUID
        - name: study
          in: query
          schema:
            type: string
            format: uuid
          description: Open specific study
        - name: series
          in: query
          schema:
            type: string
            format: uuid
          description: Open specific series (requires study parameter)
      responses:
        '200':
          description: HTML viewer page

  /api/labs/tests:
    get:
      summary: List lab test names
      description: List all lab test names available for a dossier.
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: dossier_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of test names

  /api/labs/results:
    get:
      summary: Get lab results
      description: Get lab results by test name, with optional date filtering.
      parameters:
        - name: token
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: dossier_guid
          in: query
          required: true
          schema:
            type: string
            format: uuid
        - name: names
          in: query
          required: true
          schema:
            type: string
          description: Comma-separated test names
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: Start date (YYYY-MM-DD)
        - name: to
          in: query
          schema:
            type: string
            format: date
          description: End date (YYYY-MM-DD)
        - name: latest
          in: query
          schema:
            type: boolean
          description: Return only most recent result per test
      responses:
        '200':
          description: Lab results