> ## 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 EHR actions

> The catalog of actions HealOS supports per EHR, with input and output schemas and a safety contract for each. The catalog is the same for every organization. It describes actions only: running them through the API is not available yet.

| 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 HealOS's catalog; your EHR is not contacted.
> * **Dry run:** Not needed (read-only).

> [!WARNING]
>
> This endpoint only **describes** EHR actions. Running them through the HealOS API is not available yet: there is no endpoint that executes an action.

The catalog is the same for every organization. Filter one EHR with `?ehr=athena`.

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/actions
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/actions:
    get:
      tags:
        - EHR
      summary: List EHR actions
      description: >-
        The catalog of actions HealOS supports per EHR, with input and output
        schemas and a safety contract for each. The catalog is the same for
        every organization. It describes actions only: running them through the
        API is not available yet.
      parameters:
        - schema:
            type: string
            pattern: ^[a-z0-9_]{1,64}$
            description: Only this EHR's actions.
            example: athena
          required: false
          name: ehr
          in: query
      responses:
        '200':
          description: Actions, sorted by EHR
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EhrActionListResponse'
        '400':
          description: 'Validation error: `ehr` is not a lowercase slug'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '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'
        '404':
          description: No EHR with that slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    EhrActionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/EhrAction'
        meta:
          type: object
          properties:
            total:
              type: integer
            catalog_version:
              type: integer
            ehrs:
              type: array
              items:
                $ref: '#/components/schemas/EhrSummary'
          required:
            - total
            - catalog_version
            - ehrs
      required:
        - data
        - meta
    ValidationError:
      type: object
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - error
    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
    EhrAction:
      type: object
      properties:
        name:
          type: string
          description: Stable `<ehr>.<action>` name.
          example: athena.search_patients
        version:
          type: integer
        ehr:
          type: string
          example: athena
        ehr_name:
          type: string
          example: athenahealth
        action:
          type: string
          example: search_patients
        title:
          type: string
        category:
          type: string
          enum:
            - patients
            - scheduling
            - notes
        description:
          type: string
        input_schema:
          type: object
          additionalProperties:
            nullable: true
          description: JSON Schema (draft 2020-12 subset).
        output_schema:
          type: object
          additionalProperties:
            nullable: true
          description: JSON Schema (draft 2020-12 subset).
        schema_completeness:
          type: string
          enum:
            - best_effort
          description: >-
            best_effort: fields are documented from the integration code, not
            validated per response.
        safety:
          $ref: '#/components/schemas/EhrActionSafety'
        notes:
          type: array
          items:
            type: string
        available_via:
          type: array
          nullable: true
          items:
            type: string
          description: >-
            Connection types that support the action, when the EHR has more than
            one.
        executable_via_api:
          type: boolean
          description: 'False today: running actions through the API is not available yet.'
      required:
        - name
        - version
        - ehr
        - ehr_name
        - action
        - title
        - category
        - description
        - input_schema
        - output_schema
        - schema_completeness
        - safety
        - notes
        - available_via
        - executable_via_api
    EhrSummary:
      type: object
      properties:
        ehr:
          type: string
          example: athena
        name:
          type: string
          example: athenahealth
        action_count:
          type: integer
      required:
        - ehr
        - name
        - action_count
    EhrActionSafety:
      type: object
      properties:
        writes:
          type: boolean
          description: True when the action changes data in the EHR.
        external_effect:
          type: string
          enum:
            - read
            - write
        idempotent:
          type: boolean
          description: Repeating the same request has the same effect as sending it once.
        retry_safe:
          type: boolean
          description: >-
            Safe to retry after an uncertain outcome without first checking the
            EHR. False for every write: check before retrying.
        dry_run_supported:
          type: boolean
          description: No action supports a dry run yet.
        touches_live_ehr:
          type: boolean
          description: Runs against the practice's production EHR, not a sandbox.
        ownership_check:
          type: boolean
          description: >-
            The appointment must belong to the given patient, or the action is
            refused.
        duplicate_check:
          type: boolean
          nullable: true
          description: >-
            create_patient only: HealOS searches by last name and date of birth
            first and links an exact single match instead of creating a
            duplicate. Null for other actions.
        requires_org_enablement:
          type: boolean
          description: HealOS turns this write on per practice after a supervised test.
      required:
        - writes
        - external_effect
        - idempotent
        - retry_safe
        - dry_run_supported
        - touches_live_ehr
        - ownership_check
        - duplicate_check
        - requires_org_enablement
  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.