Start a pathway execution | CAIL Health

curl -X POST https://staging.cail.health/v1/pathway-executions \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "channel": "mobile",
  "locale": "en-GB",
  "latitude": 51.5074,
  "longitude": -0.1278
}'

{
  "envelope": {
    "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
    "planDefinitionVersionId": 42,
    "channel": "mobile",
    "status": "in-progress",
    "startedAt": "2026-05-13T14:21:00.000Z"
  },
  "first": {
    "nodeId": "q.acute_chest_pain",
    "kind": "question",
    "prompt": {
      "code": "q.acute_chest_pain",
      "text": "Do you have chest pain right now?"
    },
    "options": [
      {
        "code": "yes",
        "text": "Yes"
      },
      {
        "code": "no",
        "text": "No"
      }
    ]
  }
}

Creates a channel-agnostic pathway execution and returns both the lifecycle envelope and the first node to render. The server resolves the operating organisation from the supplied coordinates, pins the execution to the current active pathway version, and flattens prompt and option text against the requested locale. The same shape serves mobile, web, voice, and call-centre channels; renderers map kind, prompt, and options onto channel-native UI. The first node is delivered inline so the client never needs a second round-trip to start rendering. Subsequent calls advance the execution via submitAnswer, then call complete or abandon.

Creates a channel-agnostic pathway execution and returns both the lifecycle envelope and the first node to render. The server resolves the operating organisation from the supplied coordinates, pins the execution to the current active pathway version, and flattens prompt and option text against the requested locale. The same shape serves mobile, web, voice, and call-centre channels; renderers map `kind`, `prompt`, and `options` onto channel-native UI. The first node is delivered inline so the client never needs a second round-trip to start rendering. Subsequent calls advance the execution via `submitAnswer`, then call `complete` or `abandon`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

planDefinitionIdstringRequired

Stable identifier of the pathway definition to execute. Must equal the active pathway pinned to the operating organisation. Stale identifiers surface a contract error code.

channelenumRequired

Channel driving the execution. Recorded for analytics only.

localestringRequired

BCP 47 language tag. All prompt and option strings in subsequent responses are flattened against this locale.

latitudedoubleRequired-90-90

Latitude at execution start (WGS84). Used by the server to resolve the operating organisation and jurisdiction.

longitudedoubleRequired-180-180

Longitude at execution start (WGS84). See latitude for resolution notes.

devicePlatformenumOptional

Calling device platform. Used by mobile and web channels for analytics. Optional on voice and call-centre.

appVersionstringOptional

Semantic version of the calling client application.

locationAccuracyMetresdoubleOptional>=0

GPS accuracy in metres. Used to flag low-confidence boundary attributions in analytics.

Response

The envelope and first node for the new execution.

envelopeobject

Lifecycle envelope for the newly-started execution.

firstobject

First node to render. Saves a second round-trip on start; the client can render immediately from this payload.