> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cail.health/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cail.health/_mcp/server.

# Start a pathway execution

POST https://staging.cail.health/v1/pathway-executions
Content-Type: application/json

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

Reference: https://docs.cail.health/api-references/api-reference/navigate-to-care/start

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: cail-api
  version: 1.0.0
paths:
  /v1/pathway-executions:
    post:
      operationId: start
      summary: Start a pathway execution
      description: >-
        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`.
      tags:
        - subpackage_navigateToCare
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The envelope and first node for the new execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartPathwayExecutionResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartPathwayExecutionRequest'
servers:
  - url: https://staging.cail.health
    description: https://staging.cail.health
components:
  schemas:
    StartPathwayExecutionRequestChannel:
      type: string
      enum:
        - mobile
        - web
        - voice
        - call-centre
      description: Channel driving the execution. Recorded for analytics only.
      title: StartPathwayExecutionRequestChannel
    StartPathwayExecutionRequestDevicePlatform:
      type: string
      enum:
        - ios
        - android
        - web
      description: >-
        Calling device platform. Used by mobile and web channels for analytics.
        Optional on voice and call-centre.
      title: StartPathwayExecutionRequestDevicePlatform
    StartPathwayExecutionRequest:
      type: object
      properties:
        planDefinitionId:
          type: string
          description: >-
            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.
        channel:
          $ref: '#/components/schemas/StartPathwayExecutionRequestChannel'
          description: Channel driving the execution. Recorded for analytics only.
        locale:
          type: string
          description: >-
            BCP 47 language tag. All prompt and option strings in subsequent
            responses are flattened against this locale.
        latitude:
          type: number
          format: double
          description: >-
            Latitude at execution start (WGS84). Used by the server to resolve
            the operating organisation and jurisdiction.
        longitude:
          type: number
          format: double
          description: >-
            Longitude at execution start (WGS84). See latitude for resolution
            notes.
        devicePlatform:
          $ref: '#/components/schemas/StartPathwayExecutionRequestDevicePlatform'
          description: >-
            Calling device platform. Used by mobile and web channels for
            analytics. Optional on voice and call-centre.
        appVersion:
          type: string
          description: Semantic version of the calling client application.
        locationAccuracyMetres:
          type: number
          format: double
          description: >-
            GPS accuracy in metres. Used to flag low-confidence boundary
            attributions in analytics.
      required:
        - planDefinitionId
        - channel
        - locale
        - latitude
        - longitude
      title: StartPathwayExecutionRequest
    PathwayExecutionEnvelopeChannel:
      type: string
      enum:
        - mobile
        - web
        - voice
        - call-centre
      description: >-
        Channel the execution is being driven through. Recorded for analytics;
        engine behaviour is identical across channels.
      title: PathwayExecutionEnvelopeChannel
    PathwayExecutionEnvelopeStatus:
      type: string
      enum:
        - in-progress
        - completed
        - abandoned
      description: >-
        Lifecycle state. One-shot transitions: in-progress to completed, or
        in-progress to abandoned.
      title: PathwayExecutionEnvelopeStatus
    PathwayExecutionEnvelope:
      type: object
      properties:
        id:
          type: string
          description: Stable identifier for the pathway execution.
        planDefinitionId:
          type: string
          description: >-
            Stable identifier of the pathway definition this execution is pinned
            to.
        planDefinitionVersionId:
          type: number
          format: double
          description: >-
            Pathway version pinned at start. All subsequent endpoint validation
            runs against this version. A mid-execution republish is invisible to
            in-flight executions.
        channel:
          $ref: '#/components/schemas/PathwayExecutionEnvelopeChannel'
          description: >-
            Channel the execution is being driven through. Recorded for
            analytics; engine behaviour is identical across channels.
        status:
          $ref: '#/components/schemas/PathwayExecutionEnvelopeStatus'
          description: >-
            Lifecycle state. One-shot transitions: in-progress to completed, or
            in-progress to abandoned.
        startedAt:
          type: string
          description: ISO 8601 timestamp at which the execution started.
        endedAt:
          type: string
          description: >-
            ISO 8601 timestamp at which the execution ended. Present when status
            is not `in-progress`.
        outcomeCode:
          type: string
          description: >-
            Outcome code for a completed execution. Mirrors the value recorded
            on the encounter row. Absent on `in-progress` and `abandoned`
            executions.
      required:
        - id
        - planDefinitionId
        - planDefinitionVersionId
        - channel
        - status
        - startedAt
      title: PathwayExecutionEnvelope
    PathwayNodeDescriptorKind:
      type: string
      enum:
        - question
        - info
        - terminal
      description: >-
        Discriminator for how to render this node. Renderers branch on this
        value before looking at the optional payloads.
      title: PathwayNodeDescriptorKind
    PathwayPromptDescriptor:
      type: object
      properties:
        code:
          type: string
          description: >-
            Authoring-time opaque identifier for the prompt. Stable across
            locales and useful for analytics correlation.
        text:
          type: string
          description: >-
            Locale-flattened rendered prompt for the request’s Accept-Language.
            Plain text only.
      required:
        - code
        - text
      title: PathwayPromptDescriptor
    PathwayOptionDescriptor:
      type: object
      properties:
        code:
          type: string
          description: >-
            Opaque branch identifier the client echoes back when submitting an
            answer.
        text:
          type: string
          description: Locale-flattened rendered option label.
      required:
        - code
        - text
      title: PathwayOptionDescriptor
    PathwayTerminalDescriptor:
      type: object
      properties:
        outcomeCode:
          type: string
          description: >-
            Outcome code from a terminal node in the pathway tree. Mirrors the
            value the engine records on the encounter row.
        routingHint:
          type: string
          description: >-
            Opaque routing hint a renderer may use to choose follow-up UX (e.g.
            show a provider list). Does not affect engine semantics.
      required:
        - outcomeCode
      title: PathwayTerminalDescriptor
    PathwayNodeDescriptor:
      type: object
      properties:
        nodeId:
          type: string
          description: Stable identifier for the current node.
        kind:
          $ref: '#/components/schemas/PathwayNodeDescriptorKind'
          description: >-
            Discriminator for how to render this node. Renderers branch on this
            value before looking at the optional payloads.
        prompt:
          $ref: '#/components/schemas/PathwayPromptDescriptor'
        options:
          type: array
          items:
            $ref: '#/components/schemas/PathwayOptionDescriptor'
          description: >-
            Selectable answers, present when kind is `question`. Order is stable
            and matches the published tree.
        terminal:
          $ref: '#/components/schemas/PathwayTerminalDescriptor'
          description: >-
            Terminal payload, present when kind is `terminal`. The engine has
            already transitioned the execution to `completed` on a response
            carrying this payload.
      required:
        - nodeId
        - kind
        - prompt
      title: PathwayNodeDescriptor
    StartPathwayExecutionResponse:
      type: object
      properties:
        envelope:
          $ref: '#/components/schemas/PathwayExecutionEnvelope'
          description: Lifecycle envelope for the newly-started execution.
        first:
          $ref: '#/components/schemas/PathwayNodeDescriptor'
          description: >-
            First node to render. Saves a second round-trip on start; the client
            can render immediately from this payload.
      required:
        - envelope
        - first
      title: StartPathwayExecutionResponse
  securitySchemes:
    firebaseBearer:
      type: http
      scheme: bearer

```

## Examples



**Request**

```json
{
  "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "channel": "mobile",
  "locale": "en-GB",
  "latitude": 51.5074,
  "longitude": -0.1278
}
```

**Response**

```json
{
  "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"
      }
    ]
  }
}
```

**SDK Code**

```python Mobile execution starting on a yes/no question node
import requests

url = "https://staging.cail.health/v1/pathway-executions"

payload = {
    "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
    "channel": "mobile",
    "locale": "en-GB",
    "latitude": 51.5074,
    "longitude": -0.1278
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Mobile execution starting on a yes/no question node
const url = 'https://staging.cail.health/v1/pathway-executions';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"planDefinitionId":"a1b2c3d4-e5f6-4789-9abc-def012345678","channel":"mobile","locale":"en-GB","latitude":51.5074,"longitude":-0.1278}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Mobile execution starting on a yes/no question node
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging.cail.health/v1/pathway-executions"

	payload := strings.NewReader("{\n  \"planDefinitionId\": \"a1b2c3d4-e5f6-4789-9abc-def012345678\",\n  \"channel\": \"mobile\",\n  \"locale\": \"en-GB\",\n  \"latitude\": 51.5074,\n  \"longitude\": -0.1278\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Mobile execution starting on a yes/no question node
require 'uri'
require 'net/http'

url = URI("https://staging.cail.health/v1/pathway-executions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"planDefinitionId\": \"a1b2c3d4-e5f6-4789-9abc-def012345678\",\n  \"channel\": \"mobile\",\n  \"locale\": \"en-GB\",\n  \"latitude\": 51.5074,\n  \"longitude\": -0.1278\n}"

response = http.request(request)
puts response.read_body
```

```java Mobile execution starting on a yes/no question node
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://staging.cail.health/v1/pathway-executions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"planDefinitionId\": \"a1b2c3d4-e5f6-4789-9abc-def012345678\",\n  \"channel\": \"mobile\",\n  \"locale\": \"en-GB\",\n  \"latitude\": 51.5074,\n  \"longitude\": -0.1278\n}")
  .asString();
```

```php Mobile execution starting on a yes/no question node
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://staging.cail.health/v1/pathway-executions', [
  'body' => '{
  "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "channel": "mobile",
  "locale": "en-GB",
  "latitude": 51.5074,
  "longitude": -0.1278
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Mobile execution starting on a yes/no question node
using RestSharp;

var client = new RestClient("https://staging.cail.health/v1/pathway-executions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"planDefinitionId\": \"a1b2c3d4-e5f6-4789-9abc-def012345678\",\n  \"channel\": \"mobile\",\n  \"locale\": \"en-GB\",\n  \"latitude\": 51.5074,\n  \"longitude\": -0.1278\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Mobile execution starting on a yes/no question node
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "planDefinitionId": "a1b2c3d4-e5f6-4789-9abc-def012345678",
  "channel": "mobile",
  "locale": "en-GB",
  "latitude": 51.5074,
  "longitude": -0.1278
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://staging.cail.health/v1/pathway-executions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```