openapi: 3.0.0
info:
  title: Playback Health Notes API
  description: REST APIs for managing clinical notes, transcriptions, and authentication
  version: 1.0.0
servers:
  - url: https://api.public.playbackhealth.com/v1
    description: Production server
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Error:
      type: object
      required:
        - success
        - message
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Error message
      example:
        success: false
        message: You are not authorized to perform this operation
    Note:
      type: object
      required:
        - id
        - url
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        url:
          type: string
          description: Pre-signed URL for file upload
          example: >-
            https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/recording-final.m4a?signed=xyz
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
        url: >-
          https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/recording-final.m4a?signed=xyz
    NoteTemplate:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        name:
          type: string
          example: Clinical Note Template
        description:
          type: string
          example: Standard template for clinical notes
        createdAt:
          type: string
          format: date-time
          example: '2025-09-11T10:00:00Z'
      example:
        id: 550e8400-e29b-41d4-a716-446655440000
        name: Clinical Note Template
        description: Standard template for clinical notes
        createdAt: '2025-09-11T10:00:00Z'
    Transcription:
      type: object
      required:
        - text
        - object
        - createdAt
      properties:
        text:
          type: string
          description: Raw transcription text
          example: Patient reports experiencing mild discomfort in the lower back...
        object:
          type: object
          description: Structured transcription data
          properties:
            segments:
              type: array
              items:
                type: object
                properties:
                  start:
                    type: number
                    example: 0
                  end:
                    type: number
                    example: 15.2
                  text:
                    type: string
                    example: Patient reports experiencing mild discomfort
        createdAt:
          type: string
          format: date-time
          example: '2025-09-11T10:00:00Z'
      example:
        text: Patient reports experiencing mild discomfort in the lower back...
        object:
          segments:
            - start: 0
              end: 15.2
              text: Patient reports experiencing mild discomfort
            - start: 15.2
              end: 30.5
              text: in the lower back region for the past two days
        createdAt: '2025-09-11T10:00:00Z'
    TranscriptionList:
      type: object
      required:
        - success
        - data
        - pagination
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            type: object
            required:
              - id
              - text
              - createdAt
              - noteId
            properties:
              id:
                type: string
                format: uuid
                description: Unique identifier for the transcription
                example: 550e8400-e29b-41d4-a716-446655440000
              text:
                type: string
                description: Raw transcription text
                example: Patient reports experiencing mild discomfort...
              createdAt:
                type: string
                format: date-time
                description: When the transcription was created
                example: '2025-09-11T10:00:00Z'
              noteId:
                type: string
                format: uuid
                description: ID of the associated note
                example: 660e8400-e29b-41d4-a716-446655440001
              status:
                type: string
                enum:
                  - pending
                  - success
                  - error
                description: Current status of the transcription
                example: success
              language:
                type: string
                description: Language of the transcription (e.g., english, spanish)
                example: english
        pagination:
          type: object
          required:
            - limit
            - offset
            - total
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 100
              example: 10
            offset:
              type: integer
              minimum: 0
              example: 0
            total:
              type: integer
              minimum: 0
              example: 45
      example:
        success: true
        data:
          - id: 550e8400-e29b-41d4-a716-446655440000
            text: Patient reports experiencing mild discomfort in the lower back...
            createdAt: '2025-09-11T10:00:00Z'
            noteId: 660e8400-e29b-41d4-a716-446655440001
            status: success
            language: english
          - id: 770e8400-e29b-41d4-a716-446655440002
            text: Follow-up visit for previous back pain complaint...
            createdAt: '2025-09-10T15:30:00Z'
            noteId: 880e8400-e29b-41d4-a716-446655440003
            status: success
            language: english
        pagination:
          limit: 10
          offset: 0
          total: 45
    NotesList:
      type: object
      required:
        - success
        - data
        - pagination
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            type: object
            required:
              - noteId
              - titleText
              - createdAt
              - email
            properties:
              noteId:
                type: string
                format: uuid
                example: 550e8400-e29b-41d4-a716-446655440000
              titleText:
                type: string
                example: Patient Follow-up Notes
              createdAt:
                type: string
                format: date-time
                example: '2025-09-11T10:00:00Z'
              email:
                type: string
                format: email
                example: doctor@playbackhealth.com
              patientId:
                type: string
                description: >
                  Patient identifier (e.g., MRN, EPIC ID, or your internal
                  patient ID).

                  This matches the identifier used when creating the note.
                example: MRN123456
        pagination:
          type: object
          required:
            - limit
            - offset
            - total
          properties:
            limit:
              type: integer
              minimum: 1
              maximum: 100
              example: 10
            offset:
              type: integer
              minimum: 0
              example: 0
            total:
              type: integer
              minimum: 0
              example: 45
      example:
        success: true
        data:
          - noteId: 550e8400-e29b-41d4-a716-446655440000
            titleText: Patient Follow-up Notes
            createdAt: '2025-09-11T10:00:00Z'
            email: doctor@playbackhealth.com
          - noteId: 660e8400-e29b-41d4-a716-446655440001
            titleText: Initial Consultation
            createdAt: '2025-09-10T15:30:00Z'
            email: doctor@playbackhealth.com
        pagination:
          limit: 10
          offset: 0
          total: 45
security:
  - BearerAuth: []
paths:
  /authorize:
    post:
      summary: Get authentication token
      description: >
        Authenticate a client using a client ID and secret to obtain an ID
        token.

        This endpoint is used for service-to-service authentication.

        The obtained token should be used as a Bearer token in subsequent API
        calls.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - clientId
                - secret
              properties:
                clientId:
                  type: string
                  description: Client identifier for authentication
                  example: internaluseradt@playbackhealth.com
                secret:
                  type: string
                  description: Secret key associated with the client
                  example: your-secret-key
            examples:
              internal_user:
                summary: Internal User Authentication
                value:
                  clientId: internaluseradt@playbackhealth.com
                  secret: internal-user-secret
              cranial_prod:
                summary: Cranial Production Authentication
                value:
                  clientId: cranial-prod@playbackhealth.com
                  secret: cranial-prod-secret
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                type: object
                required:
                  - idToken
                properties:
                  idToken:
                    type: string
                    description: JWT token to be used for subsequent API calls
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
              examples:
                success:
                  summary: Successful Authentication Response
                  value:
                    idToken: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkludGVybmFsIFVzZXIiLCJpYXQiOjE1MTYyMzkwMjJ9.abc123...
        '403':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_client:
                  summary: Invalid Client ID
                  value:
                    success: false
                    message: This user doesn't have access to this service.
                auth_failed:
                  summary: Authentication Failed
                  value:
                    success: false
                    message: Unable to authenticate with the data server.
  /notes:
    get:
      summary: Get list of notes
      description: |
        Retrieve a paginated list of clinical notes.
        Supports filtering by date range and email address.
        Results are sorted by creation date in descending order.
      parameters:
        - in: query
          name: limit
          description: Number of notes to return per page
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
          example: 10
        - in: query
          name: offset
          description: Number of notes to skip for pagination
          schema:
            type: integer
            default: 0
            minimum: 0
          example: 0
        - in: query
          name: from
          description: Start date for filtering notes (inclusive)
          schema:
            type: string
            format: date
          example: '2025-09-01'
        - in: query
          name: to
          description: End date for filtering notes (inclusive)
          schema:
            type: string
            format: date
          example: '2025-09-11'
        - in: query
          name: email
          description: Filter notes by associated email address
          schema:
            type: string
            format: email
          example: doctor@playbackhealth.com
        - in: query
          name: patientId
          description: >
            Filter notes by patient identifier (e.g., MRN, EPIC ID, or your
            internal patient ID).

            This should match the identifier used when creating the note.
          schema:
            type: string
          example: MRN123456
      responses:
        '200':
          description: List of notes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotesList'
              examples:
                success:
                  summary: Successful Notes List Response
                  value:
                    success: true
                    data:
                      - noteId: 550e8400-e29b-41d4-a716-446655440000
                        titleText: Patient Follow-up Notes
                        createdAt: '2025-09-11T10:00:00Z'
                        email: doctor@playbackhealth.com
                      - noteId: 660e8400-e29b-41d4-a716-446655440001
                        titleText: Initial Consultation
                        createdAt: '2025-09-10T15:30:00Z'
                        email: doctor@playbackhealth.com
                    pagination:
                      limit: 10
                      offset: 0
                      total: 45
                empty:
                  summary: Empty Notes List Response
                  value:
                    success: true
                    data: []
                    pagination:
                      limit: 10
                      offset: 0
                      total: 0
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_token:
                  summary: Invalid Token
                  value:
                    success: false
                    message: Token not valid
    post:
      summary: Create a new note
      description: >
        Create a new clinical note with optional template and language settings.

        Returns a pre-signed URL for uploading an audio file.

        Creates both note and transcription entries, with transcription content
        to be populated later.

        The providerId is automatically set from the authenticated user's token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                templateId:
                  type: string
                  format: uuid
                  description: Template ID to use for the note
                  example: f7c4ae9b-49cb-4f5f-bf0e-80632b940fba
                language:
                  type: string
                  default: english
                  enum:
                    - english
                    - spanish
                  description: Language of the note content
                  example: english
                patientId:
                  type: string
                  description: >
                    Any identifier for the patient from your system (e.g., MRN,
                    EPIC ID, or your internal patient ID).

                    This same identifier can be used later to retrieve notes or
                    transcriptions for the patient.
                  example: MRN123456
                audioChunkCount:
                  type: integer
                  description: >-
                    Number of audio chunks to upload. When provided and greater
                    than 0, enables chunked upload mode
                  example: 5
                addContext:
                  type: object
                  description: Additional patient context data to store as JSON in S3
                  properties:
                    patientHistory:
                      type: string
                      description: Patient's medical history
                      example: Previous back pain episodes
                    allergies:
                      type: array
                      items:
                        type: string
                      description: List of patient allergies
                      example:
                        - Penicillin
                        - Latex
                    medications:
                      type: array
                      items:
                        type: string
                      description: Current medications
                      example:
                        - Ibuprofen 200mg
                        - Vitamin D
                    symptoms:
                      type: array
                      items:
                        type: string
                      description: Current symptoms
                      example:
                        - Lower back pain
                        - Stiffness
                    notes:
                      type: string
                      description: Additional clinical notes
                      example: Patient prefers morning appointments
                  example:
                    patientHistory: Previous back pain episodes in 2020
                    allergies:
                      - Penicillin
                      - Latex
                    medications:
                      - Ibuprofen 200mg daily
                    symptoms:
                      - Lower back pain
                      - Morning stiffness
                    notes: Patient prefers morning appointments
            examples:
              with_template_and_patient:
                summary: Create Note with Template and Patient
                value:
                  templateId: f7c4ae9b-49cb-4f5f-bf0e-80632b940fba
                  language: english
                  patientId: MRN123456
              without_template:
                summary: Create Note without Template
                value:
                  language: english
                  patientId: MRN123456
              with_audio_chunks:
                summary: Create Note with Audio Chunks
                value:
                  templateId: f7c4ae9b-49cb-4f5f-bf0e-80632b940fba
                  language: english
                  patientId: MRN123456
                  audioChunkCount: 5
              with_context:
                summary: Create Note with Patient Context
                value:
                  templateId: f7c4ae9b-49cb-4f5f-bf0e-80632b940fba
                  language: english
                  patientId: MRN123456
                  addContext:
                    patientHistory: Previous back pain episodes in 2020
                    allergies:
                      - Penicillin
                      - Latex
                    medications:
                      - Ibuprofen 200mg daily
                    symptoms:
                      - Lower back pain
                      - Morning stiffness
                    notes: Patient prefers morning appointments
      responses:
        '200':
          description: Note created successfully
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - id
                      - url
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for the created note
                        example: 550e8400-e29b-41d4-a716-446655440000
                      url:
                        type: string
                        description: >-
                          Pre-signed URL for single file upload (when
                          audioChunkCount is not provided or ≤ 0)
                        example: >-
                          https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/recording-final.m4a?signed=xyz
                  - type: object
                    required:
                      - id
                      - urls
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: Unique identifier for the created note
                        example: 550e8400-e29b-41d4-a716-446655440000
                      urls:
                        type: array
                        items:
                          type: string
                        description: >-
                          Array of pre-signed URLs for chunked upload (when
                          audioChunkCount > 0)
                        example:
                          - >-
                            https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/complete-1234567890-1.m4a?signed=xyz
              examples:
                single_upload:
                  summary: Single File Upload Response
                  description: Response when audioChunkCount is not provided or ≤ 0
                  value:
                    id: f7c4ae9b-49cb-4f5f-bf0e-80632b940fba
                    url: >-
                      https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/recording-final.m4a?signed=xyz
                chunked_upload:
                  summary: Chunked Upload Response
                  description: Response when audioChunkCount > 0
                  value:
                    id: f7c4ae9b-49cb-4f5f-bf0e-80632b940fba
                    urls:
                      - >-
                        https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/complete-1234567890-1.m4a?signed=xyz
                      - >-
                        https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/complete-1234567890-2.m4a?signed=xyz
                      - >-
                        https://storage.playbackhealth.com/notes/550e8400-e29b-41d4-a716-446655440000/complete-1234567890-3.m4a?signed=xyz
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_template:
                  summary: Invalid Template ID
                  value:
                    success: false
                    message: Invalid template Id provided
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_token:
                  summary: Invalid Token
                  value:
                    success: false
                    message: Token not valid
  /notes/{id}:
    get:
      summary: Get a specific note
      description: |
        Retrieve a specific clinical note by its ID.
        Returns the note's content and metadata.
      parameters:
        - in: path
          name: id
          required: true
          description: Unique identifier of the note
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Note retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - note
                  - status
                  - createdAt
                properties:
                  note:
                    type: string
                    description: The clinical note content
                    example: Patient presented with...
                  status:
                    type: string
                    enum:
                      - pending
                      - success
                      - error
                    description: Current status of the note
                    example: success
                  createdAt:
                    type: string
                    format: date-time
                    description: Note creation timestamp
                    example: '2025-09-11T10:00:00Z'
                  template:
                    type: object
                    nullable: true
                    description: Template information used for the note
                    properties:
                      name:
                        type: string
                        description: Name of the template
                        example: Clinical Note Template
                      id:
                        type: string
                        format: uuid
                        description: ID of the template
                        example: 550e8400-e29b-41d4-a716-446655440000
                    example:
                      name: Clinical Note Template
                      id: 550e8400-e29b-41d4-a716-446655440000
                  noteObject:
                    type: object
                    nullable: true
                    description: Structured note object data
                    example: null
                  language:
                    type: string
                    description: Language of the note (e.g., english, spanish)
                    example: english
                  billingCodes:
                    type: object
                    description: >-
                      Clinical billing codes (CPT and ICD codes) associated with
                      the note
                    properties:
                      status:
                        type: string
                        enum:
                          - processing
                          - success
                        description: Status of the clinical coding data
                        example: success
                      cptCodes:
                        type: array
                        items:
                          type: object
                          required:
                            - code
                            - active
                            - confidence
                            - description
                          properties:
                            code:
                              type: string
                              description: CPT code
                              example: '99213'
                            active:
                              type: boolean
                              description: Whether the code is active/applicable
                              example: true
                            reason:
                              type: string
                              nullable: true
                              description: Reason for the code assignment
                              example: Comprehensive examination performed
                            thumbs:
                              type: string
                              nullable: true
                              description: User feedback on code accuracy
                              example: null
                            confidence:
                              type: number
                              format: float
                              minimum: 0
                              maximum: 1
                              description: AI confidence score for the code assignment
                              example: 0.9
                            description:
                              type: string
                              description: Human-readable description of the code
                              example: Office visit, established patient
                            sourceSentence:
                              type: array
                              items:
                                type: string
                              description: >-
                                Source sentences from the note that support the
                                code
                              example:
                                - On examination findings...
                        description: >-
                          Current Procedural Terminology codes with detailed
                          information
                      icdCodes:
                        type: array
                        items:
                          type: object
                          required:
                            - code
                            - active
                            - confidence
                            - description
                          properties:
                            code:
                              type: string
                              description: ICD code
                              example: J20.8
                            active:
                              type: boolean
                              description: Whether the code is active/applicable
                              example: true
                            reason:
                              type: string
                              nullable: true
                              description: Reason for the code assignment
                              example: Provider diagnoses viral bronchitis
                            thumbs:
                              type: string
                              nullable: true
                              description: User feedback on code accuracy
                              example: null
                            confidence:
                              type: number
                              format: float
                              minimum: 0
                              maximum: 1
                              description: AI confidence score for the code assignment
                              example: 0.85
                            description:
                              type: string
                              description: Human-readable description of the code
                              example: >-
                                Acute bronchitis due to other specified
                                organisms
                            sourceSentence:
                              type: array
                              items:
                                type: string
                              description: >-
                                Source sentences from the note that support the
                                code
                              example:
                                - Patient reports symptoms...
                        description: >-
                          International Classification of Diseases codes with
                          detailed information
                    example:
                      status: success
                      cptCodes:
                        - code: '99213'
                          active: true
                          reason: Comprehensive examination performed
                          thumbs: null
                          confidence: 0.9
                          description: Office visit, established patient
                          sourceSentence:
                            - On examination findings...
                      icdCodes:
                        - code: J20.8
                          active: true
                          reason: Provider diagnoses viral bronchitis
                          thumbs: null
                          confidence: 0.85
                          description: Acute bronchitis due to other specified organisms
                          sourceSentence:
                            - Patient reports symptoms...
              examples:
                success:
                  summary: Successful Note Retrieval
                  value:
                    note: >-
                      Patient presented with mild discomfort in lower back.
                      Prescribed physical therapy and follow-up in 2 weeks.
                    status: success
                    createdAt: '2025-09-11T10:00:00Z'
                    template:
                      name: Clinical Note Template
                      id: 550e8400-e29b-41d4-a716-446655440000
                    noteObject: null
                    language: english
                    billingCodes:
                      status: success
                      cptCodes:
                        - code: '99213'
                          active: true
                          reason: >-
                            Comprehensive examination performed with moderate
                            complexity decision making
                          thumbs: null
                          confidence: 0.9
                          description: >-
                            Office visit, established patient, low to moderate
                            complexity
                          sourceSentence:
                            - On examination, patient shows signs of improvement
                      icdCodes:
                        - code: M54.5
                          active: true
                          reason: >-
                            Patient reports lower back pain with specific
                            location
                          thumbs: null
                          confidence: 0.85
                          description: Low back pain
                          sourceSentence:
                            - >-
                              Patient presented with mild discomfort in lower
                              back
        '400':
          description: Invalid note ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_id:
                  summary: Invalid Note ID
                  value:
                    success: false
                    message: Please provide a valid note ID.
        '401':
          description: Unauthorized or note not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  summary: Unauthorized Access
                  value:
                    success: false
                    message: Note not found or access denied.
                invalid_token:
                  summary: Invalid Token
                  value:
                    success: false
                    message: Token not valid
  /notes/{id}/transcription:
    get:
      summary: Get transcription for a note
      description: |
        Retrieve the transcription of a clinical note's audio recording.
        Returns both raw text and structured transcription data with timestamps.
      parameters:
        - in: path
          name: id
          required: true
          description: Unique identifier of the note
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Transcription retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transcription'
              examples:
                success:
                  summary: Successful Transcription Retrieval
                  value:
                    text: >-
                      Patient reports experiencing mild discomfort in the lower
                      back region for the past two days. No radiating pain or
                      numbness. Patient denies any recent injury or trauma.
                    object:
                      segments:
                        - start: 0
                          end: 15.2
                          text: Patient reports experiencing mild discomfort
                        - start: 15.2
                          end: 30.5
                          text: in the lower back region for the past two days
                        - start: 30.5
                          end: 45.8
                          text: No radiating pain or numbness
                        - start: 45.8
                          end: 60.2
                          text: Patient denies any recent injury or trauma
                    createdAt: '2025-09-11T10:00:00Z'
        '400':
          description: Invalid note ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_id:
                  summary: Invalid Note ID
                  value:
                    success: false
                    message: Please provide a valid noteId for the transcription
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  summary: Unauthorized Access
                  value:
                    success: false
                    message: You are not authorized to perform this operation
        '404':
          description: Transcription not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not_found:
                  summary: Transcription Not Found
                  value:
                    success: false
                    message: >-
                      Transcription not found for this id, please enter valid
                      note id
  /notes/{id}/billingcodes:
    get:
      summary: Get billing codes for a note
      description: >
        Retrieve clinical billing codes (CPT and ICD codes) for a specific note.

        Returns both CPT (Current Procedural Terminology) and ICD (International
        Classification of Diseases) codes.
      parameters:
        - in: path
          name: id
          required: true
          description: Unique identifier of the note
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Billing codes retrieved successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                  - status
                  - cptCodes
                  - icdCodes
                properties:
                  success:
                    type: boolean
                    example: true
                  status:
                    type: string
                    enum:
                      - processing
                      - success
                    description: Status of the clinical coding data
                    example: success
                  cptCodes:
                    type: array
                    items:
                      type: object
                      required:
                        - code
                        - active
                        - confidence
                        - description
                      properties:
                        code:
                          type: string
                          description: CPT code
                          example: '99213'
                        active:
                          type: boolean
                          description: Whether the code is active/applicable
                          example: true
                        reason:
                          type: string
                          nullable: true
                          description: Reason for the code assignment
                          example: >-
                            Comprehensive examination performed with moderate
                            complexity decision making for established problem
                        thumbs:
                          type: string
                          nullable: true
                          description: User feedback on code accuracy
                          example: null
                        confidence:
                          type: number
                          format: float
                          minimum: 0
                          maximum: 1
                          description: AI confidence score for the code assignment
                          example: 0.9
                        description:
                          type: string
                          description: Human-readable description of the code
                          example: >-
                            Office visit, established patient, low to moderate
                            complexity
                        sourceSentence:
                          type: array
                          items:
                            type: string
                            description: >-
                              Source sentences from the note that support the
                              code
                          example:
                            - >-
                              On facial examination, there's mild pain to
                              palpation of the frontal sinuses bilaterally.
                    description: >-
                      Current Procedural Terminology codes with detailed
                      information
                  icdCodes:
                    type: array
                    items:
                      type: object
                      required:
                        - code
                        - active
                        - confidence
                        - description
                      properties:
                        code:
                          type: string
                          description: ICD code
                          example: J20.8
                        active:
                          type: boolean
                          description: Whether the code is active/applicable
                          example: true
                        reason:
                          type: string
                          nullable: true
                          description: Reason for the code assignment
                          example: >-
                            Provider explicitly diagnoses viral bronchitis based
                            on symptoms and examination findings
                        thumbs:
                          type: string
                          nullable: true
                          description: User feedback on code accuracy
                          example: null
                        confidence:
                          type: number
                          format: float
                          minimum: 0
                          maximum: 1
                          description: AI confidence score for the code assignment
                          example: 0.85
                        description:
                          type: string
                          description: Human-readable description of the code
                          example: Acute bronchitis due to other specified organisms
                        sourceSentence:
                          type: array
                          items:
                            type: string
                            description: >-
                              Source sentences from the note that support the
                              code
                          example:
                            - >-
                              So for your cough, I do believe that you most
                              likely just have a viral syndrome, like a viral
                              bronchitis.
                    description: >-
                      International Classification of Diseases codes with
                      detailed information
              examples:
                success:
                  summary: Successful Billing Codes Retrieval
                  value:
                    success: true
                    status: success
                    cptCodes:
                      - code: '99213'
                        active: true
                        reason: >-
                          Comprehensive examination performed with moderate
                          complexity decision making for established problem
                        thumbs: null
                        confidence: 0.9
                        description: >-
                          Office visit, established patient, low to moderate
                          complexity
                        sourceSentence:
                          - >-
                            On facial examination, there's mild pain to
                            palpation of the frontal sinuses bilaterally.
                          - On throat exam, the uvula is midline.
                          - >-
                            On cardiac examination, the heart is in a regular
                            rate and rhythm.
                          - >-
                            On pulmonary examination, there's chorus, ronchi,
                            bilaterally, and occasional expiratory wheezing.
                    icdCodes:
                      - code: J20.8
                        active: true
                        reason: >-
                          Provider explicitly diagnoses viral bronchitis based
                          on symptoms and examination findings
                        thumbs: null
                        confidence: 0.85
                        description: Acute bronchitis due to other specified organisms
                        sourceSentence:
                          - >-
                            So for your cough, I do believe that you most likely
                            just have a viral syndrome, like a viral bronchitis.
                      - code: Z86.718
                        active: true
                        reason: >-
                          Patient reports history of blood clot requiring
                          ongoing anticoagulation
                        thumbs: null
                        confidence: 0.95
                        description: Personal history of venous thrombosis and embolism
                        sourceSentence:
                          - >-
                            I had a blood clot in my left leg about two years
                            ago, so I'm on blood thinners.
                empty:
                  summary: No Billing Codes Found
                  value:
                    success: false
                    status: processing
                    message: Clinical coding data is still in progress.
                    cptCodes: []
                    icdCodes: []
        '400':
          description: Invalid note ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_id:
                  summary: Invalid Note ID
                  value:
                    success: false
                    message: Please provide a valid note ID.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  summary: Unauthorized Access
                  value:
                    success: false
                    message: You are not authorized to perform this operation
  /notes/{id}/finish:
    post:
      summary: Finish a note
      description: >
        Marks a note as finished by uploading an empty audio file to S3.

        This endpoint validates the note ID format, checks user access to the
        note,

        and uploads an empty audio file to trigger note processing.

        The note must belong to the authenticated user's enterprise.
      parameters:
        - in: path
          name: id
          required: true
          description: Unique identifier of the note to finish (must be valid UUID format)
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Note finished successfully
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                properties:
                  success:
                    type: boolean
                    example: true
              examples:
                success:
                  summary: Successful Note Completion
                  value:
                    success: true
        '400':
          description: Invalid request or unauthorized access to note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_note_id:
                  summary: Invalid Note ID Format
                  value:
                    success: false
                    message: Please provide a valid note ID.
                missing_note_id:
                  summary: Missing Note ID
                  value:
                    success: false
                    message: Note ID is required.
                unauthorized_note_access:
                  summary: Unauthorized Note Access
                  value:
                    success: false
                    message: You are not authorized to perform this operation
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                no_auth_header:
                  summary: No Authorization Header
                  value:
                    success: false
                    message: You are not authorized to perform this operation
                invalid_token:
                  summary: Invalid Token
                  value:
                    success: false
                    message: You are not authorized to perform this operation
                no_note_access:
                  summary: No Access to Note
                  value:
                    success: false
                    message: You are not authorized to perform this operation
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                required:
                  - success
                properties:
                  success:
                    type: boolean
                    example: false
              examples:
                server_error:
                  summary: Server Error
                  value:
                    success: false
  /transcriptions:
    get:
      summary: Get list of transcriptions
      description: |
        Retrieve a paginated list of transcriptions.
        Supports filtering by date range, status, and language.
        Results are sorted by creation date in descending order.
      parameters:
        - in: query
          name: limit
          description: Number of transcriptions to return per page
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 100
          example: 10
        - in: query
          name: offset
          description: Number of transcriptions to skip for pagination
          schema:
            type: integer
            default: 0
            minimum: 0
          example: 0
        - in: query
          name: from
          description: Start date for filtering transcriptions (inclusive)
          schema:
            type: string
            format: date
          example: '2025-09-01'
        - in: query
          name: to
          description: End date for filtering transcriptions (inclusive)
          schema:
            type: string
            format: date
          example: '2025-09-11'
        - in: query
          name: status
          description: Filter by transcription status
          schema:
            type: string
            enum:
              - pending
              - success
              - error
          example: success
        - in: query
          name: language
          description: Filter by transcription language
          schema:
            type: string
            enum:
              - english
              - spanish
          example: english
        - in: query
          name: noteId
          description: Filter by associated note ID
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        - in: query
          name: patientId
          description: >
            Filter transcriptions by patient identifier (e.g., MRN, EPIC ID, or
            your internal patient ID).

            This should match the identifier used when creating the note.
          schema:
            type: string
          example: MRN123456
      responses:
        '200':
          description: List of transcriptions retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranscriptionList'
              examples:
                success:
                  summary: Successful Transcriptions List
                  value:
                    success: true
                    data:
                      - id: 550e8400-e29b-41d4-a716-446655440000
                        text: >-
                          Patient reports experiencing mild discomfort in the
                          lower back...
                        createdAt: '2025-09-11T10:00:00Z'
                        noteId: 660e8400-e29b-41d4-a716-446655440001
                        status: success
                        language: english
                      - id: 770e8400-e29b-41d4-a716-446655440002
                        text: Follow-up visit for previous back pain complaint...
                        createdAt: '2025-09-10T15:30:00Z'
                        noteId: 880e8400-e29b-41d4-a716-446655440003
                        status: success
                        language: english
                    pagination:
                      limit: 10
                      offset: 0
                      total: 45
                filtered:
                  summary: Filtered by Status and Date
                  value:
                    success: true
                    data:
                      - id: 550e8400-e29b-41d4-a716-446655440000
                        text: >-
                          Patient reports experiencing mild discomfort in the
                          lower back...
                        createdAt: '2025-09-11T10:00:00Z'
                        noteId: 660e8400-e29b-41d4-a716-446655440001
                        status: success
                        language: english
                    pagination:
                      limit: 10
                      offset: 0
                      total: 1
                empty:
                  summary: No Results Found
                  value:
                    success: true
                    data: []
                    pagination:
                      limit: 10
                      offset: 0
                      total: 0
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_date:
                  summary: Invalid Date Format
                  value:
                    success: false
                    message: Invalid date format. Please use YYYY-MM-DD format.
                invalid_status:
                  summary: Invalid Status
                  value:
                    success: false
                    message: >-
                      Invalid status value. Must be one of: pending, success, or
                      error.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                unauthorized:
                  summary: Unauthorized Access
                  value:
                    success: false
                    message: You are not authorized to perform this operation
