Amigo Form Templates API

openapi: 3.2.0
info:
  title: Platform Form Templates API
  description: Management API for the Amigo platform. Provides CRUD operations for workspaces, API keys, and resources.
  version: 1.0.0
servers:
- url: https://api.platform.amigo.ai
  description: Production
security:
- BearerAuth: []
tags:
- name: Form Templates
paths:
  /v1/{workspace_id}/settings/form-templates:
    get:
      tags:
      - Form Templates
      summary: List Form Templates
      description: List all form templates for a workspace.
      operationId: list-form-templates
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - intake
            - update
            - consent
            - screening
            - survey
            - custom
            type: string
          - type: 'null'
          title: Category
      - name: patient_type
        in: query
        required: false
        schema:
          anyOf:
          - enum:
            - new
            - returning
            - any
            type: string
          - type: 'null'
          title: Patient Type
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplateListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Form Templates
      summary: Update Form Templates
      description: Replace all form templates for a workspace.
      operationId: update-form-templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormTemplateUpdateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplateListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/settings/form-templates/{template_id}:
    get:
      tags:
      - Form Templates
      summary: Get Form Template
      description: Get a single form template by ID.
      operationId: get-form-template
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Template Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormTemplate-Output'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/settings/form-templates/{template_id}/resolve:
    post:
      tags:
      - Form Templates
      summary: Resolve Form Template
      description: 'Resolve a form template with prefill values from entity state.


        Returns a hydrated SurfaceSpec ready to be passed to create_surface.

        Fields with matching data in entity state get prefill_value set.

        For returning patient templates, completed optional fields are stripped.'
      operationId: resolve-form-template
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Template Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResolveTemplateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolveTemplateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FormTemplate-Input:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          $ref: '#/components/schemas/NameString'
        description:
          anyOf:
          - $ref: '#/components/schemas/DescriptionString'
          - type: 'null'
        category:
          type: string
          enum:
          - intake
          - update
          - consent
          - screening
          - survey
          - custom
          title: Category
          default: custom
        patient_type:
          type: string
          enum:
          - new
          - returning
          - any
          title: Patient Type
          default: any
        fields:
          items:
            $ref: '#/components/schemas/FormTemplateField'
          type: array
          maxItems: 200
          minItems: 1
          title: Fields
        sections:
          items:
            $ref: '#/components/schemas/FormTemplateSection'
          type: array
          maxItems: 20
          minItems: 1
          title: Sections
        branding:
          anyOf:
          - $ref: '#/components/schemas/BrandingConfig'
          - type: 'null'
        completion_title:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Completion Title
        completion_message:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Completion Message
        completion_action_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Completion Action Url
        submit_button_text:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Submit Button Text
        active:
          type: boolean
          title: Active
          default: true
        version:
          type: integer
          minimum: 1.0
          title: Version
          default: 1
      type: object
      required:
      - name
      - fields
      - sections
      title: FormTemplate
      description: 'Reusable form template with sections, prefill, branding.


        Extends DataTemplate concept. Up to 200 fields, organized in sections.

        Stored in workspace settings["form_templates"] JSONB.


        Examples:

        - New patient intake (85 fields, 11 sections)

        - Returning patient update (27 fields, 5 sections)

        - Pre-surgery checklist (15 fields, 3 sections)

        - PHQ-9 screening (10 fields, 1 section)'
    SurfaceSection:
      properties:
        title:
          $ref: '#/components/schemas/NameString'
        description:
          anyOf:
          - $ref: '#/components/schemas/DescriptionString'
          - type: 'null'
        field_keys:
          items:
            type: string
          type: array
          maxItems: 100
          minItems: 1
          title: Field Keys
        condition:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Condition
      type: object
      required:
      - title
      - field_keys
      title: SurfaceSection
      description: A page/step in a multi-page surface form.
    FieldType:
      type: string
      enum:
      - text
      - textarea
      - date
      - phone
      - email
      - number
      - select
      - multiselect
      - checkbox
      - photo
      - signature
      - file
      - heading
      - info
      title: FieldType
      description: Input field types for surface data collection.
    SurfaceField:
      properties:
        key:
          type: string
          maxLength: 128
          minLength: 1
          title: Key
        label:
          $ref: '#/components/schemas/NameString'
        field_type:
          $ref: '#/components/schemas/FieldType'
        required:
          type: boolean
          title: Required
          default: true
        options:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Options
        description:
          anyOf:
          - $ref: '#/components/schemas/DescriptionString'
          - type: 'null'
        placeholder:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Placeholder
        prefill_value:
          anyOf:
          - {}
          - type: 'null'
          title: Prefill Value
        validation:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Validation
        sensitive:
          type: boolean
          title: Sensitive
          default: false
        condition:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Condition
        consent_text:
          anyOf:
          - type: string
            maxLength: 5000
          - type: 'null'
          title: Consent Text
      type: object
      required:
      - key
      - label
      - field_type
      title: SurfaceField
      description: 'A single data collection field in a surface spec.


        Generated by agents from HSM analysis. Each field maps

        to a specific piece of data the world model needs.'
    FormTemplateSection:
      properties:
        id:
          type: string
          maxLength: 64
          minLength: 1
          title: Id
        title:
          $ref: '#/components/schemas/NameString'
        description:
          anyOf:
          - $ref: '#/components/schemas/DescriptionString'
          - type: 'null'
        field_keys:
          items:
            type: string
          type: array
          maxItems: 200
          minItems: 1
          title: Field Keys
        condition:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Condition
      type: object
      required:
      - id
      - title
      - field_keys
      title: FormTemplateSection
      description: A section in a form template (maps to one wizard step).
    ChannelType:
      type: string
      enum:
      - email
      - web
      - sms
      title: ChannelType
      description: Delivery channels for surfaces.
    FormTemplateField:
      properties:
        key:
          type: string
          maxLength: 128
          minLength: 1
          title: Key
        label:
          $ref: '#/components/schemas/NameString'
        field_type:
          $ref: '#/components/schemas/FieldType'
          default: text
        required:
          type: boolean
          title: Required
          default: true
        options:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Options
        description:
          anyOf:
          - $ref: '#/components/schemas/DescriptionString'
          - type: 'null'
        placeholder:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Placeholder
        validation:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Validation
        sensitive:
          type: boolean
          title: Sensitive
          default: false
        condition:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Condition
        consent_text:
          anyOf:
          - type: string
            maxLength: 5000
          - type: 'null'
          title: Consent Text
        prefill_path:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Prefill Path
          description: Dot-notation path into entity state for prefill (e.g. demographics.date_of_birth)
        layout_group:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Layout Group
          description: Row grouping hint — fields with same layout_group render side-by-side
      type: object
      required:
      - key
      - label
      title: FormTemplateField
      description: 'Extended field with prefill_path mapping to entity state.


        Unlike SurfaceField (agent-generated, dynamic), FormTemplateField is

        a reusable definition that maps to FHIR/EHR data paths for auto-prefill.'
    SurfaceSpec:
      properties:
        entity_id:
          type: string
          format: uuid
          title: Entity Id
        title:
          $ref: '#/components/schemas/NameString'
        description:
          anyOf:
          - $ref: '#/components/schemas/DescriptionString'
          - type: 'null'
        fields:
          items:
            $ref: '#/components/schemas/SurfaceField'
          type: array
          maxItems: 200
          minItems: 1
          title: Fields
        channel:
          $ref: '#/components/schemas/ChannelType'
          default: web
        expires_in_hours:
          type: integer
          maximum: 8760.0
          minimum: 1.0
          title: Expires In Hours
          default: 168
        context:
          additionalProperties: true
          type: object
          title: Context
        resource_type:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Resource Type
        branding:
          anyOf:
          - $ref: '#/components/schemas/BrandingConfig'
          - type: 'null'
        sections:
          anyOf:
          - items:
              $ref: '#/components/schemas/SurfaceSection'
            type: array
          - type: 'null'
          title: Sections
        completion_title:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Completion Title
        completion_message:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Completion Message
        completion_action_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Completion Action Url
        submit_button_text:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Submit Button Text
      type: object
      required:
      - entity_id
      - title
      - fields
      title: SurfaceSpec
      description: 'A complete surface specification generated by an agent.


        The agent reads the HSM (entity state, relationships,

        confidence gaps) and produces this spec. The spec is stored as a

        world.event and rendered by platform-api into a patient-facing page.'
    FormTemplateUpdateRequest:
      properties:
        templates:
          items:
            $ref: '#/components/schemas/FormTemplate-Input'
          type: array
          maxItems: 50
          title: Templates
      type: object
      required:
      - templates
      title: FormTemplateUpdateRequest
      description: Replace all form templates.
    ResolveTemplateResponse:
      properties:
        spec:
          $ref: '#/components/schemas/SurfaceSpec'
        prefilled_count:
          type: integer
          title: Prefilled Count
        total_fields:
          type: integer
          title: Total Fields
      type: object
      required:
      - spec
      - prefilled_count
      - total_fields
      title: ResolveTemplateResponse
      description: Resolved SurfaceSpec with prefill values.
    DescriptionString:
      type: string
      maxLength: 2000
    NameString:
      type: string
      maxLength: 256
      minLength: 1
    BrandingConfig:
      properties:
        logo_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Logo Url
        primary_color:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Primary Color
        background_color:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Background Color
        font_family:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Font Family
      type: object
      title: BrandingConfig
      description: Visual branding for patient-facing surfaces.
    FormTemplateListResponse:
      properties:
        templates:
          items:
            $ref: '#/components/schemas/FormTemplate-Output'
          type: array
          title: Templates
      type: object
      required:
      - templates
      title: FormTemplateListResponse
      description: List of form templates for a workspace.
    FormTemplate-Output:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          $ref: '#/components/schemas/NameString'
        description:
          anyOf:
          - $ref: '#/components/schemas/DescriptionString'
          - type: 'null'
        category:
          type: string
          enum:
          - intake
          - update
          - consent
          - screening
          - survey
          - custom
          title: Category
          default: custom
        patient_type:
          type: string
          enum:
          - new
          - returning
          - any
          title: Patient Type
          default: any
        fields:
          items:
            $ref: '#/components/schemas/FormTemplateField'
          type: array
          maxItems: 200
          minItems: 1
          title: Fields
        sections:
          items:
            $ref: '#/components/schemas/FormTemplateSection'
          type: array
          maxItems: 20
          minItems: 1
          title: Sections
        branding:
          anyOf:
          - $ref: '#/components/schemas/BrandingConfig'
          - type: 'null'
        completion_title:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Completion Title
        completion_message:
          anyOf:
          - type: string
            maxLength: 2000
          - type: 'null'
          title: Completion Message
        completion_action_url:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Completion Action Url
        submit_button_text:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Submit Button Text
        active:
          type: boolean
          title: Active
          default: true
        version:
          type: integer
          minimum: 1.0
          title: Version
          default: 1
      type: object
      required:
      - name
      - fields
      - sections
      title: FormTemplate
      description: 'Reusable form template with sections, prefill, branding.


        Extends DataTemplate concept. Up to 200 fields, organized in sections.

        Stored in workspace settings["form_templates"] JSONB.


        Examples:

        - New patient intake (85 fields, 11 sections)

        - Returning patient update (27 fields, 5 sections)

        - Pre-surgery checklist (15 fields, 3 sections)

        - PHQ-9 screening (10 fields, 1 section)'
    ResolveTemplateRequest:
      properties:
        entity_id:
          type: string
          format: uuid
          title: Entity Id
      type: object
      required:
      - entity_id
      title: ResolveTemplateRequest
      description: Resolve a form template for a specific entity.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token.