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

# Author and publish a care pathway

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](/api-reference/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`.

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

```bash
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](/concepts/fhir-r4-in-cail) `PlanDefinition` resource and the decision tree, flattened to the request locale.

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

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

* See the pathway in action in [Navigate a member to care](/guides/navigate-a-member-to-care).
* Review every pathway endpoint in the [API Reference](/api-reference/introduction).