Guides

Author and publish a care pathway

Draft, revise, and activate a routing pathway
View as MarkdownOpen in Claude

This guide shows how an operator authors a care pathway, from an empty draft to an active pathway that members are routed through. Every call here is an operator-path call; authenticate as an operator client first. See Authentication.

A pathway is the routing logic for a jurisdiction. The flow has four stages: create a draft, revise it, review it, then publish.

Step 1: Create a draft

A draft is an unpublished pathway in development. An organisation may hold only one draft at a time. Create it with POST /v1/plan-definitions/draft.

$curl --request POST "$CAIL_API_BASE_URL/v1/plan-definitions/draft" \
>  --header "Authorization: Bearer $CAIL_TOKEN" \
>  --header "Content-Type: application/json" \
>  --data '{
>    "name": "acute-respiratory",
>    "version": "2.4.0",
>    "title": "Acute respiratory triage",
>    "description": "Triage flow for acute respiratory symptoms in adults."
>  }'

The response returns the draft id. You can include an initial decisionTree here, or submit the draft empty and build the tree in the next step.

Step 2: Revise the draft

Edit the draft with PATCH /v1/plan-definitions/{id}/draft. Only the fields you send change; everything else is preserved.

Every update uses optimistic locking. Send the draft’s current versionId in expectedVersionId. If it does not match the server, the call returns a 409 Conflict. Refetch the draft, then retry with the current value.

$curl --request PATCH "$CAIL_API_BASE_URL/v1/plan-definitions/{id}/draft" \
>  --header "Authorization: Bearer $CAIL_TOKEN" \
>  --header "Content-Type: application/json" \
>  --data '{
>    "expectedVersionId": 7,
>    "title": "Acute respiratory triage (revised)",
>    "description": "Adds an updated cough-duration question and an emergency outcome."
>  }'

The decision tree is authored content the routing engine consumes. Treat it as opaque JSON in this API.

Step 3: Review the draft

Before publishing, fetch the full pathway with GET /v1/plan-definitions/{id}. The response includes the FHIR R4 PlanDefinition resource and the decision tree, flattened to the request locale.

$curl --get "$CAIL_API_BASE_URL/v1/plan-definitions/{id}" \
>  --header "Authorization: Bearer $CAIL_TOKEN"

Step 4: Publish the draft

When the draft is ready, activate it with POST /v1/plan-definitions/{id}/publish. The pathway becomes the active pathway for its jurisdiction, and members are routed through it.

$curl --request POST "$CAIL_API_BASE_URL/v1/plan-definitions/{id}/publish" \
>  --header "Authorization: Bearer $CAIL_TOKEN"

From this point, the published pathway is what GET /v1/plan-definitions/active resolves for a member at a covered location.

Next steps