Ctrlk
Go to website
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Surfaces

List Surfaces

get

List surfaces with pagination and optional filters.

Permissions: viewer, member, admin, owner (surfaces:read)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
entity_idstring · uuid · nullableOptional

Filter by entity ID

statusstring · nullableOptional

Filter by status

channelstring · nullableOptional

Filter by channel

Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/surfaces
GET /v1/{workspace_id}/surfaces HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "event_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "text",
      "description": "text",
      "status": "created",
      "channel": "email",
      "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
      "fields_count": 1,
      "fields": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "resource_type": "text",
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "expires_at": "text",
      "created_at": "text",
      "delivered_at": "text",
      "opened_at": "text",
      "submitted_at": "text",
      "submitted_data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "delivery_metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "review_notes": "text",
      "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
      "reviewed_at": "text",
      "archived_at": "text",
      "archive_reason": "text",
      "url": "text"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Create Surface

post

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)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Body

Request to create a new surface.

The agent generates a SurfaceSpec and sends it here.

entity_idstring · uuidRequired
titlestring · min: 1 · max: 256Required
descriptionstring · max: 2000 · nullableOptional
channelstring · enumOptional

Delivery channels for surfaces.

Default: webPossible values:
use_case_idstring · uuid · nullableOptional
expires_in_hoursinteger · min: 1 · max: 8760OptionalDefault: 168
resource_typestring · max: 64 · nullableOptional
completion_titlestring · max: 256 · nullableOptional
completion_messagestring · max: 2000 · nullableOptional
completion_action_urlstring · max: 2048 · nullableOptional
submit_button_textstring · max: 128 · nullableOptional
Responses
200

Successful Response

application/json
idstring · uuidRequired
event_idstring · uuidRequired
entity_idstring · uuidRequired
titlestringRequired
descriptionstring · nullableOptional
statusstring · enumRequired

Lifecycle status of a surface.

Possible values:
channelstring · enumRequired

Delivery channels for surfaces.

Possible values:
use_case_idstring · uuid · nullableOptional
fields_countintegerRequired
expires_atstringRequired
created_atstringRequired
tokenstring · nullableOptional
urlstring · nullableOptional
post/v1/{workspace_id}/surfaces
POST /v1/{workspace_id}/surfaces HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 892

{
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "fields": [
    {
      "key": "text",
      "label": "text",
      "field_type": "text",
      "required": true,
      "options": [
        "text"
      ],
      "description": "text",
      "placeholder": "text",
      "prefill_value": null,
      "validation": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "sensitive": false,
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "consent_text": "text"
    }
  ],
  "channel": "web",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "expires_in_hours": 168,
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "resource_type": "text",
  "branding": {
    "logo_url": "text",
    "primary_color": "text",
    "background_color": "text",
    "font_family": "text"
  },
  "sections": [
    {
      "title": "text",
      "description": "text",
      "field_keys": [
        "text"
      ],
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "completion_title": "text",
  "completion_message": "text",
  "completion_action_url": "text",
  "submit_button_text": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "expires_at": "text",
  "created_at": "text",
  "token": "text",
  "url": "text"
}

List surfaces pending review

get

List surfaces pending review.

Field engineers use this to approve or reject surfaces before delivery.

Permissions: operator, member, admin, owner (ReviewQueue:View)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
Query parameters
limitinteger · max: 200OptionalDefault: 50
continuation_tokenanyOptional
Responses
200

Successful Response

application/json
has_morebooleanRequired
continuation_tokenanyOptional
get/v1/{workspace_id}/surfaces/review
GET /v1/{workspace_id}/surfaces/review HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "event_id": "123e4567-e89b-12d3-a456-426614174000",
      "entity_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "text",
      "description": "text",
      "status": "created",
      "channel": "email",
      "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
      "fields_count": 1,
      "fields": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "resource_type": "text",
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "expires_at": "text",
      "created_at": "text",
      "delivered_at": "text",
      "opened_at": "text",
      "submitted_at": "text",
      "submitted_data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "delivery_metadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "review_notes": "text",
      "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
      "reviewed_at": "text",
      "archived_at": "text",
      "archive_reason": "text",
      "url": "text"
    }
  ],
  "has_more": true,
  "continuation_token": null
}

Get Surface

get

Get a surface by ID.

Returns the surface spec and current lifecycle status. Also mints the patient-facing url so operators can copy/share the link from the read view (the token isn't stored, so it's re-minted on each read).

Permissions: viewer, member, admin, owner (surfaces:read)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Responses
200

Successful Response

application/json
idstring · uuidRequired
event_idstring · uuidRequired
entity_idstring · uuid · nullableOptional
titlestring · nullableOptional
descriptionstring · nullableOptional
statusstring · enumRequired

Lifecycle status of a surface.

Possible values:
channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:
use_case_idstring · uuid · nullableOptional
fields_countintegerRequired
resource_typestring · nullableOptional
expires_atstring · nullableOptional
created_atstring · nullableOptional
delivered_atstring · nullableOptional
opened_atstring · nullableOptional
submitted_atstring · nullableOptional
review_notesstring · nullableOptional
reviewed_bystring · uuid · nullableOptional
reviewed_atstring · nullableOptional
archived_atstring · nullableOptional
archive_reasonstring · nullableOptional
urlstring · nullableOptional
get/v1/{workspace_id}/surfaces/{surface_id}
GET /v1/{workspace_id}/surfaces/{surface_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "fields": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "resource_type": "text",
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "expires_at": "text",
  "created_at": "text",
  "delivered_at": "text",
  "opened_at": "text",
  "submitted_at": "text",
  "submitted_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "delivery_metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "review_notes": "text",
  "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
  "reviewed_at": "text",
  "archived_at": "text",
  "archive_reason": "text",
  "url": "text"
}

Archive (soft-delete) a surface

delete

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)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Responses
200

Successful Response

application/json
surface_idstring · uuidRequired
statusconst: archivedRequired
delete/v1/{workspace_id}/surfaces/{surface_id}
DELETE /v1/{workspace_id}/surfaces/{surface_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "text"
}

Update a surface spec

patch

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)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Body

Partial update to an existing surface.

All fields are optional. Only provided fields are merged into the spec. Only allowed while status is CREATED or DELIVERED.

titlestring · min: 1 · max: 256 · nullableOptional
descriptionstring · max: 2000 · nullableOptional
completion_titlestring · max: 256 · nullableOptional
completion_messagestring · max: 2000 · nullableOptional
completion_action_urlstring · max: 2048 · nullableOptional
submit_button_textstring · max: 128 · nullableOptional
channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:
resource_typestring · max: 64 · nullableOptional
Responses
200

Successful Response

application/json
idstring · uuidRequired
event_idstring · uuidRequired
entity_idstring · uuid · nullableOptional
titlestring · nullableOptional
descriptionstring · nullableOptional
statusstring · enumRequired

Lifecycle status of a surface.

Possible values:
channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:
use_case_idstring · uuid · nullableOptional
fields_countintegerRequired
resource_typestring · nullableOptional
expires_atstring · nullableOptional
created_atstring · nullableOptional
delivered_atstring · nullableOptional
opened_atstring · nullableOptional
submitted_atstring · nullableOptional
review_notesstring · nullableOptional
reviewed_bystring · uuid · nullableOptional
reviewed_atstring · nullableOptional
archived_atstring · nullableOptional
archive_reasonstring · nullableOptional
urlstring · nullableOptional
patch/v1/{workspace_id}/surfaces/{surface_id}
PATCH /v1/{workspace_id}/surfaces/{surface_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 718

{
  "title": "text",
  "description": "text",
  "fields": [
    {
      "key": "text",
      "label": "text",
      "field_type": "text",
      "required": true,
      "options": [
        "text"
      ],
      "description": "text",
      "placeholder": "text",
      "prefill_value": null,
      "validation": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "sensitive": false,
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "consent_text": "text"
    }
  ],
  "branding": {
    "logo_url": "text",
    "primary_color": "text",
    "background_color": "text",
    "font_family": "text"
  },
  "sections": [
    {
      "title": "text",
      "description": "text",
      "field_keys": [
        "text"
      ],
      "condition": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    }
  ],
  "completion_title": "text",
  "completion_message": "text",
  "completion_action_url": "text",
  "submit_button_text": "text",
  "channel": "email",
  "resource_type": "text"
}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "fields": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "resource_type": "text",
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "expires_at": "text",
  "created_at": "text",
  "delivered_at": "text",
  "opened_at": "text",
  "submitted_at": "text",
  "submitted_data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "delivery_metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "review_notes": "text",
  "reviewed_by": "123e4567-e89b-12d3-a456-426614174000",
  "reviewed_at": "text",
  "archived_at": "text",
  "archive_reason": "text",
  "url": "text"
}

Approve a surface pending review

post

Approve a surface pending review.

The surface returns to CREATED status and can then be delivered.

Permissions: operator, member, admin, owner (ReviewQueue:Review)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Responses
200

Successful Response

application/json
surface_idstring · uuidRequired
statusstring · enumRequired

Lifecycle status of a surface.

Possible values:
actionstring · enumRequiredPossible values:
post/v1/{workspace_id}/surfaces/{surface_id}/approve
POST /v1/{workspace_id}/surfaces/{surface_id}/approve HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "action": "approved"
}

Reject a surface pending review

post

Reject a surface pending review.

The surface is marked as expired and will not be delivered.

Permissions: operator, member, admin, owner (ReviewQueue:Review)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Body
reasonstring · max: 2000 · nullableOptional
Responses
200

Successful Response

application/json
surface_idstring · uuidRequired
statusstring · enumRequired

Lifecycle status of a surface.

Possible values:
actionstring · enumRequiredPossible values:
post/v1/{workspace_id}/surfaces/{surface_id}/reject
POST /v1/{workspace_id}/surfaces/{surface_id}/reject HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "reason": "text"
}
{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "created",
  "action": "approved"
}

Get field-level completion status

get

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)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Responses
200

Successful Response

application/json
surface_idstring · uuidRequired
total_fieldsintegerRequired
filled_countintegerRequired
empty_countintegerRequired
filled_keysstring[]Required
empty_keysstring[]Required
required_empty_keysstring[]Required
get/v1/{workspace_id}/surfaces/{surface_id}/progress
GET /v1/{workspace_id}/surfaces/{surface_id}/progress HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "total_fields": 1,
  "filled_count": 1,
  "empty_count": 1,
  "filled_keys": [
    "text"
  ],
  "empty_keys": [
    "text"
  ],
  "required_empty_keys": [
    "text"
  ]
}

Create new surface with only unfilled fields

post

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)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Responses
200

Successful Response

application/json
idstring · uuidRequired
event_idstring · uuidRequired
entity_idstring · uuidRequired
titlestringRequired
descriptionstring · nullableOptional
statusstring · enumRequired

Lifecycle status of a surface.

Possible values:
channelstring · enumRequired

Delivery channels for surfaces.

Possible values:
use_case_idstring · uuid · nullableOptional
fields_countintegerRequired
expires_atstringRequired
created_atstringRequired
tokenstring · nullableOptional
urlstring · nullableOptional
post/v1/{workspace_id}/surfaces/{surface_id}/reshape
POST /v1/{workspace_id}/surfaces/{surface_id}/reshape HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "event_id": "123e4567-e89b-12d3-a456-426614174000",
  "entity_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "text",
  "description": "text",
  "status": "created",
  "channel": "email",
  "use_case_id": "123e4567-e89b-12d3-a456-426614174000",
  "fields_count": 1,
  "expires_at": "text",
  "created_at": "text",
  "token": "text",
  "url": "text"
}

Deliver Surface

post

Record a real delivery handoff for a surface.

Email targets are delivered through channel-manager's POST /v1/email/ (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)

Authorizations
AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters
workspace_idstring · uuidRequired
surface_idstring · uuidRequired
Body

Request to mark a surface as delivered.

channel_addressstring · min: 1 · max: 256Required

Delivery address (phone number, email, etc.)

Responses
200

Successful Response

application/json
surface_idstring · uuidRequired
statusstring · enumRequiredPossible values:
channelstring · enum · nullableOptional

Delivery channels for surfaces.

Possible values:
urlstring · nullableOptional
channel_addressstringRequired
message_idstring · nullableOptional
from_numberstring · nullableOptional
from_addressstring · nullableOptional
delivery_providerstring · nullableOptional
delivered_atstring · nullableOptional
post/v1/{workspace_id}/surfaces/{surface_id}/deliver
POST /v1/{workspace_id}/surfaces/{surface_id}/deliver HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 26

{
  "channel_address": "text"
}
{
  "surface_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "delivered",
  "channel": "email",
  "url": "text",
  "channel_address": "text",
  "message_id": "text",
  "from_number": "text",
  "from_address": "text",
  "delivery_provider": "text",
  "delivered_at": "text"
}
PreviousIntakeNextEvents

Last updated

Was this helpful?