Surface Patient

Redirect To Surface

get

Short-URL redirect: /s/f/{surface_id} → /s/{token}.

Generates a fresh HMAC token and issues a 302 redirect so that SMS messages can contain a short, clickable link instead of the long base64-encoded token URL.

Authorizations

AuthorizationstringRequired

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

Path parameters

surface_idstring · uuidRequired

Responses

200

Successful Response

application/json

anyOptional

302

Redirect to full surface URL

404

Surface not found

410

Surface expired

422

Validation Error

application/json

get/s/f/{surface_id}

GET /s/f/{surface_id} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Lookup Field

get

Search healthcare reference data for form field autocompletion.

Supports: medication (RxNorm), allergy (RxNorm), pharmacy (NPPES NPI), insurance (static carrier list). Token-authenticated, no Bearer auth.

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

lookup_typestringRequired

Query parameters

qstring · min: 2 · max: 200Required

Responses

200

Successful Response

application/json

Autocompletion results for a surface lookup field.

401

Invalid token

application/json

422

Invalid lookup type

application/json

429

Rate limited

get/s/{token}/lookup/{lookup_type}

GET /s/{token}/lookup/{lookup_type}?q=text HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ]
}

Ocr Extract

post

Extract structured data from an image (e.g. insurance card) using Gemini Vision.

Returns extracted field key-value pairs and a confidence score. Token-authenticated, no Bearer auth.

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

Body

imagestring · min: 1 · max: 10000000Required

Base64-encoded image data

target_fieldsstring[] · max: 50 · nullableOptional

Optional list of field keys to extract

Responses

200

Successful Response

application/json

Structured field extraction result for an uploaded image.

confidencenumber · max: 1Required

401

Invalid token

application/json

422

Validation Error

application/json

429

Rate limited

post/s/{token}/ocr

POST /s/{token}/ocr HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "image": "text",
  "target_fields": [
    "text"
  ]
}

{
  "extracted_fields": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "confidence": 1
}

Render Surface

get

Render a patient-facing surface as HTML.

Token-authenticated — no Bearer auth required. Records a surface.opened lifecycle event on first 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

tokenstringRequired

Responses

200

Successful Response

application/json

anyOptional

401

Invalid token

410

Token expired

422

Validation Error

application/json

429

Rate limited

get/s/{token}

GET /s/{token} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Get Surface Spec

get

Return surface spec as JSON for the forms app.

The forms app (Next.js) calls this on SSR to fetch the spec, saved field values, and merged branding. Records surface.opened event on first access.

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

Responses

200

Successful Response

application/json

Surface render bundle returned to forms-app SSR.

surface_idstring · max: 64 · nullableOptional

entity_idstring · max: 64 · nullableOptional

statusstring · max: 64 · nullableOptional

401

Invalid token

application/json

404

Surface not found

application/json

409

Already submitted

application/json

410

Token expired or surface archived

application/json

422

Validation Error

application/json

429

Rate limited

get/s/{token}/spec

GET /s/{token}/spec HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "surface_id": "text",
  "entity_id": "text",
  "status": "text",
  "spec": {
    "title": "text",
    "description": "text",
    "fields": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "sections": [
      {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "branding": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "submit_button_text": "text",
    "completion_title": "text",
    "completion_message": "text",
    "completion_action_url": "text",
    "context": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  },
  "saved_values": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

Get Availability

get

Return available appointment slots for the surface's workspace.

Queries FHIR Slot resources from world.entities_synced that are free and within the requested date range. Token-authenticated, no Bearer auth.

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

Query parameters

datestring · nullableOptional

ISO date (YYYY-MM-DD) to start search

daysinteger · min: 1 · max: 30Optional

Number of days to search forward

Default: 7

Responses

200

Successful Response

application/json

Available appointment slots grouped by date.

401

Invalid token

application/json

410

Token expired

application/json

422

Invalid date format

application/json

429

Rate limited

get/s/{token}/availability

GET /s/{token}/availability HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "dates": [
    {
      "date": "text",
      "slots": [
        {
          "id": "text",
          "start": "text",
          "end": "text",
          "provider": "text"
        }
      ]
    }
  ]
}

Book Appointment

post

Submit a booking request for a specific slot.

Writes a booking.requested world event tied to the surface's entity. Token-authenticated, no Bearer auth.

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

Body

slot_idstring · min: 1 · max: 256Required

The FHIR Slot ID to book

Responses

200

Successful Response

application/json

Acknowledgement returned when a booking request is accepted.

statusconst: pendingRequired

Booking lifecycle status.

messagestring · max: 512Required

slot_idstring · max: 256Required

401

Invalid token

application/json

404

Slot not found

application/json

409

Slot unavailable

application/json

410

Token expired

application/json

422

Validation error

application/json

429

Rate limited

post/s/{token}/book

POST /s/{token}/book HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "slot_id": "text"
}

{
  "status": "text",
  "message": "text",
  "slot_id": "text"
}

Heal Field

post

Auto-heal a form field value using Claude Haiku.

Best-effort LLM correction — returns original value with confidence 0 if the service is unavailable or inference fails. Token-authenticated, no Bearer auth.

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

Body

keystring · min: 1 · max: 128Required

valuestring · min: 1 · max: 2000Required

field_typestring · max: 32Required

labelstring · max: 256Required

sensitivebooleanOptionalDefault: false

Responses

200

Successful Response

application/json

corrected_valuestring · max: 4000Required

explanationstring · max: 2000 · nullableOptional

confidencenumber · max: 1Required

401

Invalid token

application/json

422

Validation Error

application/json

429

Rate limited

post/s/{token}/heal

POST /s/{token}/heal HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 131

{
  "key": "text",
  "value": "text",
  "field_type": "text",
  "label": "text",
  "sensitive": false,
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "corrected_value": "text",
  "explanation": "text",
  "confidence": 1
}

Submit Surface

post

Submit a patient-facing surface form.

Accepts standard HTML form POST. Writes surface.submitted event with confidence 0.5 (self-reported data).

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

Responses

200

Successful Response

application/json

anyOptional

401

Invalid token

409

Already submitted

410

Token expired

422

Validation Error

application/json

429

Rate limited

post/s/{token}/submit

POST /s/{token}/submit HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Save Field

put

Auto-save a single field value.

Called by client-side JavaScript on field blur. Writes surface.field_saved event with confidence 0.5.

Authorizations

AuthorizationstringRequired

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

Path parameters

tokenstringRequired

keystringRequired

Body

valueanyRequired

The field value to save

Responses

200

Successful Response

application/json

Acknowledgement returned when a field is auto-saved.

statusconst: savedOptionalDefault: saved

401

Invalid token

application/json

413

Payload too large

application/json

422

Validation Error

application/json

429

Rate limited

500

Save failed

application/json

put/s/{token}/fields/{key}

PUT /s/{token}/fields/{key} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "value": null
}

{
  "status": "saved"
}