> ## 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 a template

> One template with its sections and each section's instructions. Built-in templates, templates shared with your organization, and the key owner's own private templates (the same set POST /sessions/{sessionId}/notes/regenerate accepts as `template_id`). A template from another organization is a 404. Requires the templates:read scope.

| Requirement | Detail |
| - | - |
| **Scope** | `templates:read` (rolling out: not yet on `api.healos.ai`) |
| **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).

Guide: [Templates](https://docs.healos.ai/templates.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /templates/{templateId}
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:
  /templates/{templateId}:
    get:
      tags:
        - Templates
      summary: Get a template
      description: >-
        One template with its sections and each section's instructions. Built-in
        templates, templates shared with your organization, and the key owner's
        own private templates (the same set POST
        /sessions/{sessionId}/notes/regenerate accepts as `template_id`). A
        template from another organization is a 404. Requires the templates:read
        scope.
      parameters:
        - schema:
            type: string
            format: uuid
            description: Template identifier, from GET /templates.
            example: 77777777-0000-0000-0000-000000000001
          required: true
          name: templateId
          in: path
      responses:
        '200':
          description: The template
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateDetailResponse'
        '400':
          description: 'Validation error: `templateId` is not a UUID'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Template not found in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    TemplateDetailResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/TemplateDetail'
      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
    TemplateDetail:
      type: object
      properties:
        id:
          type: string
          description: >-
            Template identifier. Pass it as `template_id` to POST
            /sessions/{sessionId}/notes/regenerate.
          example: 77777777-0000-0000-0000-000000000001
        name:
          type: string
          description: Template name as shown in HealOS
          example: SOAP Note
        type:
          type: string
          enum:
            - built_in
            - custom
          description: >-
            `built_in`: a HealOS template available to every organization.
            `custom`: a template created in your organization and shared with
            it.
          example: custom
        document_type:
          type: string
          enum:
            - note
            - document
          description: >-
            `note` for clinical note templates, `document` for document
            templates (letters, forms).
          example: note
        description:
          type: string
          nullable: true
          description: >-
            Short summary of the template: its section titles, in order. Null
            when the template has no titled sections.
          example: Subjective, Objective, Assessment, Plan
        includes_prior_visit:
          type: boolean
          description: >-
            Whether notes generated with this template include the patient's
            previous visit by default.
          example: false
        sections:
          type: array
          items:
            $ref: '#/components/schemas/TemplateSection'
          description: Sections in order, with their instructions.
      required:
        - id
        - name
        - type
        - document_type
        - description
        - includes_prior_visit
        - sections
    TemplateSection:
      type: object
      properties:
        key:
          type: string
          description: Stable section key; the heading key in generated notes.
          example: subjective
        title:
          type: string
          example: Subjective
        instructions:
          type: string
          nullable: true
          description: >-
            What the section asks the note generator to write. Null when the
            section has no instructions HealOS can show (a custom section owned
            by another clinician in a legacy template).
          example: Chief complaint and history of present illness.
      required:
        - key
        - title
        - instructions
  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.