> ## 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. # Get an EHR action > One action's input and output schemas and safety contract, by its stable `.` name. | 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. Look an action up by its stable `.` name, for example `athena.search_patients`. 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/{actionName} 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/{actionName}: get: tags: - EHR summary: Get an EHR action description: >- One action's input and output schemas and safety contract, by its stable `.` name. parameters: - schema: type: string pattern: ^[a-z0-9_]{1,64}\.[a-z0-9_]{1,64}$ example: athena.search_patients required: true name: actionName in: path responses: '200': description: The action content: application/json: schema: $ref: '#/components/schemas/EhrActionResponse' '400': description: 'Validation error: the name is not `.`' 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 action with that name content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitError' components: schemas: EhrActionResponse: type: object properties: data: $ref: '#/components/schemas/EhrAction' required: - data 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 `.` 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 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.