# Form Templates

## List Form Templates

> List all form templates for a workspace.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"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."}},"schemas":{"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,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"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.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"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."},"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)."},"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."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"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"}}}}}}}}}
```

## Update Form Templates

> Replace all form templates for a workspace.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"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."}},"schemas":{"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."},"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,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"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.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"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."},"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)."},"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,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/v1/{workspace_id}/settings/form-templates":{"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"}}]}}}}
```

## Get Form Template

> Get a single form template by ID.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"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."}},"schemas":{"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,"title":"Version","default":1}},"type":"object","required":["name","fields","sections"],"title":"FormTemplate","description":"Reusable form template with sections, prefill, branding.\n\nExtends DataTemplate concept. Up to 200 fields, organized in sections.\nStored in workspace settings[\"form_templates\"] JSONB.\n\nExamples:\n- New patient intake (85 fields, 11 sections)\n- Returning patient update (27 fields, 5 sections)\n- Pre-surgery checklist (15 fields, 3 sections)\n- PHQ-9 screening (10 fields, 1 section)"},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"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.\n\nUnlike SurfaceField (agent-generated, dynamic), FormTemplateField is\na reusable definition that maps to FHIR/EHR data paths for auto-prefill."},"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."},"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)."},"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."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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"}}}}}}}}}
```

## Resolve Form Template

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

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"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."}},"schemas":{"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."},"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."},"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,"minimum":1,"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.\n\nThe agent reads the HSM (entity state, relationships,\nconfidence gaps) and produces this spec. The spec is stored as a\nworld.event and rendered by platform-api into a patient-facing page."},"NameString":{"type":"string","maxLength":256,"minLength":1},"DescriptionString":{"type":"string","maxLength":2000},"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.\n\nGenerated by agents from HSM analysis. Each field maps\nto a specific piece of data the world model needs."},"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."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"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."},"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."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"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"}}},"paths":{"/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.\n\nReturns a hydrated SurfaceSpec ready to be passed to create_surface.\nFields with matching data in entity state get prefill_value set.\nFor 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"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/form-templates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.