> ## 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.

# List your EHR connections

> Every EHR in the catalog with whether your organization has it connected. Status only: never credentials, sessions or which user connected it.

| Requirement | Detail |
| - | - |
| **Scope** | `ehr: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. Reads your organization's connection status in HealOS; your EHR is not contacted.
> * **Dry run:** Not needed (read-only).

Returns, for each EHR in the catalog, only whether **the key's own organization** has it connected. It never returns credentials, sessions or which user connected it.

Guide: [EHR integrations](https://docs.healos.ai/ehr-actions/overview.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /ehr/connections
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:
  /ehr/connections:
    get:
      tags:
        - EHR
      summary: List your EHR connections
      description: >-
        Every EHR in the catalog with whether your organization has it
        connected. Status only: never credentials, sessions or which user
        connected it.
      responses:
        '200':
          description: One row per catalog EHR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EhrConnectionListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs ehr:read)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    EhrConnectionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EhrConnection'
      required:
        - data
    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
    EhrConnection:
      type: object
      properties:
        ehr:
          type: string
          example: athena
        name:
          type: string
          example: athenahealth
        status:
          type: string
          enum:
            - connected
            - not_connected
        action_count:
          type: integer
          description: Actions the catalog lists for this EHR.
      required:
        - ehr
        - name
        - status
        - action_count
  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.