# Surfaces

## List Surfaces

> List surfaces with pagination and optional filters.\
> \
> Permissions: viewer, member, admin, owner (surfaces:read)

```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":{"PaginatedResponse_SurfaceResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SurfaceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[SurfaceResponse]"},"SurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields","default":[]},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opened At"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"submitted_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Submitted Data"},"delivery_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Delivery Metadata"}},"type":"object","required":["id","event_id","status","fields_count"],"title":"SurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for 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}/surfaces":{"get":{"tags":["Surfaces"],"summary":"List Surfaces","description":"List surfaces with pagination and optional filters.\n\nPermissions: viewer, member, admin, owner (surfaces:read)","operationId":"list-surfaces","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by entity ID","title":"Entity Id"},"description":"Filter by entity ID"},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by status","title":"Status"},"description":"Filter by status"},{"name":"channel","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by channel","title":"Channel"},"description":"Filter by channel"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_SurfaceResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Create Surface

> Create a new data collection surface.\
> \
> Stores the surface spec as a world.event with domain="surface".\
> The entity\_id is stored inside event data (not on the event row)\
> to avoid entity state recomputation.\
> \
> Returns a signed patient-facing token and URL if SURFACE\_TOKEN\_SECRET is configured.\
> \
> Permissions: member, admin, owner (surfaces:write)

```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":{"CreateSurfaceRequest":{"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"},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"expires_in_hours":{"type":"integer","maximum":8760,"minimum":1,"title":"Expires In Hours","default":168},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"resource_type":{"anyOf":[{"type":"string","maxLength":64},{"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":"CreateSurfaceRequest","description":"Request to create a new surface.\n\nThe agent generates a SurfaceSpec and sends it here."},"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."},"CreateSurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"$ref":"#/components/schemas/ChannelType"},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"expires_at":{"type":"string","title":"Expires At"},"created_at":{"type":"string","title":"Created At"},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["id","event_id","entity_id","title","status","channel","fields_count","expires_at","created_at"],"title":"CreateSurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."}}},"paths":{"/v1/{workspace_id}/surfaces":{"post":{"tags":["Surfaces"],"summary":"Create Surface","description":"Create a new data collection surface.\n\nStores the surface spec as a world.event with domain=\"surface\".\nThe entity_id is stored inside event data (not on the event row)\nto avoid entity state recomputation.\n\nReturns a signed patient-facing token and URL if SURFACE_TOKEN_SECRET is configured.\n\nPermissions: member, admin, owner (surfaces:write)","operationId":"create-surface","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSurfaceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSurfaceResponse"}}}},"422":{"description":"Validation error"},"429":{"description":"Rate limited"}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## List surfaces pending review

> List surfaces pending review.\
> \
> Field engineers use this to approve or reject surfaces before delivery.\
> \
> Permissions: operator, member, admin, owner (ReviewQueue:View)

```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":{"PaginatedResponse_SurfaceResponse_":{"properties":{"items":{"items":{"$ref":"#/components/schemas/SurfaceResponse"},"type":"array","title":"Items"},"has_more":{"type":"boolean","title":"Has More"},"continuation_token":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Continuation Token"},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total"}},"type":"object","required":["items","has_more"],"title":"PaginatedResponse[SurfaceResponse]"},"SurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields","default":[]},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opened At"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"submitted_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Submitted Data"},"delivery_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Delivery Metadata"}},"type":"object","required":["id","event_id","status","fields_count"],"title":"SurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for 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}/surfaces/review":{"get":{"tags":["Surfaces"],"summary":"List surfaces pending review","description":"List surfaces pending review.\n\nField engineers use this to approve or reject surfaces before delivery.\n\nPermissions: operator, member, admin, owner (ReviewQueue:View)","operationId":"list-surface-review-queue","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"exclusiveMinimum":0,"default":10,"title":"Limit"}},{"name":"continuation_token","in":"query","required":false,"schema":{"type":"integer","default":0,"title":"Continuation Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedResponse_SurfaceResponse_"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Get Surface

> Get a surface by ID.\
> \
> Returns the surface spec and current lifecycle status.\
> \
> Permissions: viewer, member, admin, owner (surfaces:read)

```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":{"SurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields","default":[]},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opened At"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"submitted_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Submitted Data"},"delivery_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Delivery Metadata"}},"type":"object","required":["id","event_id","status","fields_count"],"title":"SurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for 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}/surfaces/{surface_id}":{"get":{"tags":["Surfaces"],"summary":"Get Surface","description":"Get a surface by ID.\n\nReturns the surface spec and current lifecycle status.\n\nPermissions: viewer, member, admin, owner (surfaces:read)","operationId":"get-surface","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfaceResponse"}}}},"404":{"description":"Surface not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Archive (soft-delete) a surface

> Archive (soft-delete) a surface.\
> \
> Works for any non-terminal surface. Terminal surfaces (completed,\
> expired, already archived) cannot be archived.\
> \
> Permissions: member, admin, owner (Surface:Create)

```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":{"ArchiveResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"status":{"type":"string","const":"archived","title":"Status"}},"type":"object","required":["surface_id","status"],"title":"ArchiveResponse"},"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}/surfaces/{surface_id}":{"delete":{"tags":["Surfaces"],"summary":"Archive (soft-delete) a surface","description":"Archive (soft-delete) a surface.\n\nWorks for any non-terminal surface. Terminal surfaces (completed,\nexpired, already archived) cannot be archived.\n\nPermissions: member, admin, owner (Surface:Create)","operationId":"archive-surface","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveResponse"}}}},"404":{"description":"Surface not found"},"409":{"description":"Cannot archive terminal surface"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Update a surface spec

> Update an existing surface spec.\
> \
> Only allowed while status is CREATED or DELIVERED. Writes a\
> surface.updated event preserving the full audit trail.\
> \
> Permissions: member, admin, owner (Surface:Create)

```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":{"UpdateSurfaceRequest":{"properties":{"title":{"anyOf":[{"$ref":"#/components/schemas/NameString"},{"type":"null"}]},"description":{"anyOf":[{"$ref":"#/components/schemas/DescriptionString"},{"type":"null"}]},"fields":{"anyOf":[{"items":{"$ref":"#/components/schemas/SurfaceField"},"type":"array","maxItems":200,"minItems":1},{"type":"null"}],"title":"Fields"},"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"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"resource_type":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Resource Type"}},"type":"object","title":"UpdateSurfaceRequest","description":"Partial update to an existing surface.\n\nAll fields are optional. Only provided fields are merged into the spec.\nOnly allowed while status is CREATED or DELIVERED."},"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."},"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."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."},"SurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Entity Id"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"fields":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Fields","default":[]},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type"},"context":{"additionalProperties":true,"type":"object","title":"Context","default":{}},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expires At"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"},"opened_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Opened At"},"submitted_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Submitted At"},"submitted_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Submitted Data"},"delivery_metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Delivery Metadata"}},"type":"object","required":["id","event_id","status","fields_count"],"title":"SurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."}}},"paths":{"/v1/{workspace_id}/surfaces/{surface_id}":{"patch":{"tags":["Surfaces"],"summary":"Update a surface spec","description":"Update an existing surface spec.\n\nOnly allowed while status is CREATED or DELIVERED. Writes a\nsurface.updated event preserving the full audit trail.\n\nPermissions: member, admin, owner (Surface:Create)","operationId":"update-surface","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSurfaceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfaceResponse"}}}},"404":{"description":"Surface not found"},"409":{"description":"Cannot update in current status"},"422":{"description":"Validation error"},"429":{"description":"Rate limited"}}}}}}
```

## Approve a surface pending review

> Approve a surface pending review.\
> \
> The surface returns to CREATED status and can then be delivered.\
> \
> Permissions: operator, member, admin, owner (ReviewQueue:Review)

```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":{"ReviewActionResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"action":{"type":"string","enum":["approved","rejected"],"title":"Action"}},"type":"object","required":["surface_id","status","action"],"title":"ReviewActionResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"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}/surfaces/{surface_id}/approve":{"post":{"tags":["Surfaces"],"summary":"Approve a surface pending review","description":"Approve a surface pending review.\n\nThe surface returns to CREATED status and can then be delivered.\n\nPermissions: operator, member, admin, owner (ReviewQueue:Review)","operationId":"approve-surface","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewActionResponse"}}}},"404":{"description":"Surface not found"},"409":{"description":"Surface is not pending review"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Reject a surface pending review

> Reject a surface pending review.\
> \
> The surface is marked as expired and will not be delivered.\
> \
> Permissions: operator, member, admin, owner (ReviewQueue:Review)

```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":{"RejectSurfaceRequest":{"properties":{"reason":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Reason"}},"type":"object","title":"RejectSurfaceRequest"},"ReviewActionResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"action":{"type":"string","enum":["approved","rejected"],"title":"Action"}},"type":"object","required":["surface_id","status","action"],"title":"ReviewActionResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"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}/surfaces/{surface_id}/reject":{"post":{"tags":["Surfaces"],"summary":"Reject a surface pending review","description":"Reject a surface pending review.\n\nThe surface is marked as expired and will not be delivered.\n\nPermissions: operator, member, admin, owner (ReviewQueue:Review)","operationId":"reject-surface","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectSurfaceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewActionResponse"}}}},"404":{"description":"Surface not found"},"409":{"description":"Surface is not pending review"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Get field-level completion status

> Get field-level completion status for a surface.\
> \
> Returns which fields are filled vs empty, useful for abandonment\
> intelligence and targeted re-engagement.\
> \
> Permissions: viewer, member, admin, owner (surfaces:read)

```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":{"SurfaceProgressResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"total_fields":{"type":"integer","title":"Total Fields"},"filled_count":{"type":"integer","title":"Filled Count"},"empty_count":{"type":"integer","title":"Empty Count"},"filled_keys":{"items":{"type":"string"},"type":"array","title":"Filled Keys"},"empty_keys":{"items":{"type":"string"},"type":"array","title":"Empty Keys"},"required_empty_keys":{"items":{"type":"string"},"type":"array","title":"Required Empty Keys"}},"type":"object","required":["surface_id","total_fields","filled_count","empty_count","filled_keys","empty_keys","required_empty_keys"],"title":"SurfaceProgressResponse"},"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}/surfaces/{surface_id}/progress":{"get":{"tags":["Surfaces"],"summary":"Get field-level completion status","description":"Get field-level completion status for a surface.\n\nReturns which fields are filled vs empty, useful for abandonment\nintelligence and targeted re-engagement.\n\nPermissions: viewer, member, admin, owner (surfaces:read)","operationId":"get-surface-progress","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurfaceProgressResponse"}}}},"404":{"description":"Surface not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Create new surface with only unfilled fields

> Create a new surface with only the unfilled fields from the original.\
> \
> Used for re-engaging patients who abandoned a form. The new surface\
> contains only the fields they haven't completed yet, reducing friction.\
> \
> Permissions: member, admin, owner (surfaces:write)

```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":{"CreateSurfaceResponse":{"properties":{"id":{"type":"string","format":"uuid","title":"Id"},"event_id":{"type":"string","format":"uuid","title":"Event Id"},"entity_id":{"type":"string","format":"uuid","title":"Entity Id"},"title":{"type":"string","title":"Title"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"status":{"$ref":"#/components/schemas/SurfaceStatus"},"channel":{"$ref":"#/components/schemas/ChannelType"},"use_case_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Use Case Id"},"fields_count":{"type":"integer","title":"Fields Count"},"expires_at":{"type":"string","title":"Expires At"},"created_at":{"type":"string","title":"Created At"},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"}},"type":"object","required":["id","event_id","entity_id","title","status","channel","fields_count","expires_at","created_at"],"title":"CreateSurfaceResponse"},"SurfaceStatus":{"type":"string","enum":["created","pending_review","delivered","opened","partial","completed","expired","archived"],"title":"SurfaceStatus","description":"Lifecycle status of a surface."},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for 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}/surfaces/{surface_id}/reshape":{"post":{"tags":["Surfaces"],"summary":"Create new surface with only unfilled fields","description":"Create a new surface with only the unfilled fields from the original.\n\nUsed for re-engaging patients who abandoned a form. The new surface\ncontains only the fields they haven't completed yet, reducing friction.\n\nPermissions: member, admin, owner (surfaces:write)","operationId":"reshape-surface","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSurfaceResponse"}}}},"404":{"description":"Surface not found"},"409":{"description":"All fields already filled"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Deliver Surface

> Record a real delivery handoff for a surface.\
> \
> Email targets are delivered through channel-manager's\
> \`\`POST /v1/email/send\`\` (CM owns SES sender identity, IP pool, DKIM,\
> suppression — keyed on the surface row's \`\`use\_case\_id\`\`). Phone-shaped\
> addresses return 422 — SMS surface delivery was removed in PR #2783.\
> Other targets record an external handoff that was completed outside\
> platform-api.\
> \
> Permissions: member, admin, owner (surfaces:write)

```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":{"DeliverSurfaceRequest":{"properties":{"channel_address":{"type":"string","maxLength":256,"minLength":1,"title":"Channel Address","description":"Delivery address (phone number, email, etc.)"}},"type":"object","required":["channel_address"],"title":"DeliverSurfaceRequest","description":"Request to mark a surface as delivered."},"DeliverSurfaceResponse":{"properties":{"surface_id":{"type":"string","format":"uuid","title":"Surface Id"},"status":{"type":"string","enum":["delivered","pending_review"],"title":"Status"},"channel":{"anyOf":[{"$ref":"#/components/schemas/ChannelType"},{"type":"null"}]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url"},"channel_address":{"type":"string","title":"Channel Address"},"message_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message Id"},"from_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Number"},"from_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From Address"},"delivery_provider":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivery Provider"},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Delivered At"}},"type":"object","required":["surface_id","status","channel_address"],"title":"DeliverSurfaceResponse"},"ChannelType":{"type":"string","enum":["email","web","sms"],"title":"ChannelType","description":"Delivery channels for surfaces."}}},"paths":{"/v1/{workspace_id}/surfaces/{surface_id}/deliver":{"post":{"tags":["Surfaces"],"summary":"Deliver Surface","description":"Record a real delivery handoff for a surface.\n\nEmail targets are delivered through channel-manager's\n``POST /v1/email/send`` (CM owns SES sender identity, IP pool, DKIM,\nsuppression — keyed on the surface row's ``use_case_id``). Phone-shaped\naddresses return 422 — SMS surface delivery was removed in PR #2783.\nOther targets record an external handoff that was completed outside\nplatform-api.\n\nPermissions: member, admin, owner (surfaces:write)","operationId":"deliver-surface","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"surface_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Surface Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverSurfaceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverSurfaceResponse"}}}},"404":{"description":"Surface not found"},"409":{"description":"Surface already delivered/completed/expired"},"422":{"description":"Validation error"},"429":{"description":"Rate limited"}}}}}}
```


---

# 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/surfaces.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.