> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Export clinical notes

> Every note matching the same filters as GET /notes, with full content, codes, transcript and patient context. `json` (default) and `csv` return at most 1000 notes (`meta.truncated`, or the `X-Result-Truncated` header on csv, says when more matched); `ndjson` streams the full set, one note per line.

| Requirement | Detail |
| - | - |
| **Scope** | `notes:read` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!TIP]
>
> **Safety**
>
> * **Writes data:** No
> * **Safe to retry:** Yes
> * **Contacts an outside system:** None
> * **Dry run:** Not needed (read-only).

Pick the format with `format`: `json` (default) and `csv` return at most 1000 notes (`meta.truncated`, or the `X-Result-Truncated` header on csv, says when more matched); `ndjson` streams every matching note, one per line. Narrow large pulls with `from` and `to`. The response holds full note content, transcripts and patient context: store it as PHI.

Guide: [Clinical notes: export notes](https://docs.healos.ai/clinical-notes.md#export-notes). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /notes/export
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /notes/export:
    get:
      tags:
        - Notes
      summary: Export clinical notes
      description: >-
        Every note matching the same filters as GET /notes, with full content,
        codes, transcript and patient context. `json` (default) and `csv` return
        at most 1000 notes (`meta.truncated`, or the `X-Result-Truncated` header
        on csv, says when more matched); `ndjson` streams the full set, one note
        per line.
      parameters:
        - schema:
            type: string
            description: Filter by patient ID.
            example: '481926357104938271'
          required: false
          name: patient_id
          in: query
        - schema:
            type: string
            description: Filter by session ID.
            example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          required: false
          name: session_id
          in: query
        - schema:
            type: string
            description: Filter by the template the note was generated from.
          required: false
          name: template_id
          in: query
        - schema:
            type: string
            description: Filter by authoring clinician (must be a member of your org).
          required: false
          name: created_by
          in: query
        - schema:
            type: string
            description: Filter by note type.
            example: clinical_visit
          required: false
          name: note_type
          in: query
        - schema:
            type: string
            description: Only notes created on/after this date (ISO 8601).
            example: '2026-01-01'
          required: false
          name: from
          in: query
        - schema:
            type: string
            description: Only notes created on/before this date (ISO 8601).
            example: '2026-06-30'
          required: false
          name: to
          in: query
        - schema:
            type: string
            enum:
              - json
              - csv
              - ndjson
            default: json
            description: >-
              Export format. `json` (default) returns a nested array (capped);
              `csv` returns a flattened table (capped); `ndjson` streams one
              note per line with no row cap.
            example: json
          required: false
          name: format
          in: query
      responses:
        '200':
          description: The matching notes, in the requested format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoteExportResponse'
            text/csv:
              schema:
                type: string
            application/x-ndjson:
              schema:
                type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    NoteExportResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NoteDetail'
        meta:
          type: object
          properties:
            count:
              type: number
              description: Number of notes returned.
            truncated:
              type: boolean
              description: >-
                True when the result was capped; narrow filters or use
                format=ndjson for the full set.
          required:
            - count
            - truncated
      required:
        - data
        - meta
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
    NoteDetail:
      allOf:
        - $ref: '#/components/schemas/NoteListItem'
        - type: object
          properties:
            content:
              type: string
              nullable: true
              description: The clinical note body.
            problems:
              type: array
              items:
                type: string
              example:
                - Hypertension
            procedures:
              type: array
              items:
                type: string
              example:
                - 12-lead ECG
            icd10_codes:
              type: object
              nullable: true
              additionalProperties:
                nullable: true
              description: 'ICD-10 codes, e.g. { "I10": "Essential hypertension" }'
            cpt_codes:
              type: object
              nullable: true
              additionalProperties:
                nullable: true
              description: CPT codes keyed by procedure.
            transcript:
              $ref: '#/components/schemas/NoteTranscript'
            patient:
              $ref: '#/components/schemas/NotePatientContext'
          required:
            - content
            - problems
            - procedures
            - icd10_codes
            - cpt_codes
            - transcript
            - patient
    NoteListItem:
      type: object
      properties:
        id:
          type: string
          example: 9b2d4f6a-1c3e-4a5b-8d7f-0e1a2b3c4d5e
        patient_id:
          type: string
          nullable: true
          example: '481926357104938271'
        session_id:
          type: string
          nullable: true
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        note_type:
          type: string
          nullable: true
          example: clinical_visit
        specialty:
          type: string
          nullable: true
          example: Cardiology
        template_id:
          type: string
          nullable: true
        template_name:
          type: string
          nullable: true
          example: Follow-Up Patient Visit
        model:
          type: string
          nullable: true
          description: >-
            Read-only. The note quality that produced the note (fast, balanced,
            or detailed), the same choices as the `model` option when
            generating. Null for older notes without this record, or when no
            model wrote the note (a basic fallback note).
          example: balanced
        created_at:
          type: string
          nullable: true
          example: '2026-03-15T09:30:00.000Z'
        updated_at:
          type: string
          nullable: true
          example: '2026-03-15T10:00:00.000Z'
      required:
        - id
        - patient_id
        - session_id
        - note_type
        - specialty
        - template_id
        - template_name
        - model
        - created_at
        - updated_at
    NoteTranscript:
      type: object
      nullable: true
      properties:
        text:
          type: string
          nullable: true
          description: Full session transcript.
        summary:
          type: string
          nullable: true
          description: Session summary.
        title:
          type: string
          nullable: true
          example: Follow-up visit
        status:
          type: string
          nullable: true
          description: Transcript status.
          example: completed
        session_date:
          type: string
          nullable: true
          description: Session date (ISO 8601).
        start_time:
          type: string
          nullable: true
          description: Session start (ISO 8601).
        end_time:
          type: string
          nullable: true
          description: Session end (ISO 8601).
      required:
        - text
        - summary
        - title
        - status
        - session_date
        - start_time
        - end_time
      description: Included unless excluded via `include`.
    NotePatientContext:
      type: object
      nullable: true
      properties:
        id:
          type: string
          example: '481926357104938271'
        name:
          type: string
          nullable: true
          example: Maria Santos
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        pronouns:
          type: string
          nullable: true
          example: she/her
        date_of_birth:
          type: string
          nullable: true
          example: '1985-04-12'
        gender:
          type: string
          nullable: true
          example: female
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        mrn:
          type: string
          nullable: true
          example: MRN-00123
        client_history:
          $ref: '#/components/schemas/ClientHistory'
      required:
        - id
        - name
        - first_name
        - last_name
        - pronouns
        - date_of_birth
        - gender
        - email
        - phone
        - mrn
        - client_history
      description: Included unless excluded via `include`.
    ClientHistory:
      type: object
      nullable: true
      properties:
        medical_history:
          type: string
          nullable: true
        family_history:
          type: string
          nullable: true
        social_history:
          type: string
          nullable: true
        previous_treatment:
          type: string
          nullable: true
      required:
        - medical_history
        - family_history
        - social_history
        - previous_treatment
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.