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

# Create a pathway draft

POST https://staging.cail.health/v1/plan-definitions/draft
Content-Type: application/json

Creates a new pathway draft owned by the operator’s organisation. Drafts are unpublished pathways in development; only one draft per organisation may exist at a time. Submit the empty draft and edit the tree via update, or include an initial decisionTree if your tooling is set up to author it. Returns the new identifier and the draft status acknowledgement.

Reference: https://docs.cail.health/api-references/api-reference/understand-coverage/create-draft

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: cail-api
  version: 1.0.0
paths:
  /v1/plan-definitions/draft:
    post:
      operationId: create-draft
      summary: Create a pathway draft
      description: >-
        Creates a new pathway draft owned by the operator’s organisation. Drafts
        are unpublished pathways in development; only one draft per organisation
        may exist at a time. Submit the empty draft and edit the tree via
        update, or include an initial decisionTree if your tooling is set up to
        author it. Returns the new identifier and the draft status
        acknowledgement.
      tags:
        - subpackage_understandCoverage
      parameters:
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The newly-created draft.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDraftPlanDefinitionResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDraftPlanDefinitionRequest'
servers:
  - url: https://staging.cail.health
    description: https://staging.cail.health
components:
  schemas:
    CreateDraftPlanDefinitionRequest:
      type: object
      properties:
        name:
          type: string
          description: Machine-readable name for the pathway. Used in URLs and analytics.
        version:
          type: string
          description: Semantic version assigned by the pathway authors.
        title:
          type: string
          description: Human-readable title for the pathway.
        description:
          type: string
          description: Free-text description of the pathway’s purpose and scope.
        decisionTree:
          type: object
          additionalProperties:
            description: Any type
          description: >-
            Initial decision-tree structure. Pathway authors typically create
            the draft empty and edit the tree via update; the field is
            documented here so existing tooling that submits a tree on create
            remains supported. Decision tree shape is internal and may evolve;
            consumers should treat it as opaque JSON and use the dedicated
            pathway-execution endpoints to traverse it.
      required:
        - name
        - version
        - title
      title: CreateDraftPlanDefinitionRequest
    CreatedDraftPlanDefinitionStatus:
      type: string
      enum:
        - draft
      description: Lifecycle status of the new row.
      title: CreatedDraftPlanDefinitionStatus
    CreatedDraftPlanDefinition:
      type: object
      properties:
        id:
          type: string
          description: Stable identifier of the newly-created draft.
        status:
          $ref: '#/components/schemas/CreatedDraftPlanDefinitionStatus'
          description: Lifecycle status of the new row.
      required:
        - id
        - status
      title: CreatedDraftPlanDefinition
    CreateDraftPlanDefinitionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CreatedDraftPlanDefinition'
        message:
          type: string
          description: Human-readable acknowledgement.
      required:
        - data
        - message
      title: CreateDraftPlanDefinitionResponse
  securitySchemes:
    auth0Bearer:
      type: http
      scheme: bearer

```

## Examples



**Request**

```json
{
  "name": "acute-respiratory",
  "version": "2.4.0",
  "title": "Acute respiratory triage"
}
```

**Response**

```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-4789-9abc-def012345678",
    "status": "draft"
  },
  "message": "Draft created successfully"
}
```

**SDK Code**

```python A fresh draft for an acute respiratory pathway
import requests

url = "https://staging.cail.health/v1/plan-definitions/draft"

payload = {
    "name": "acute-respiratory",
    "version": "2.4.0",
    "title": "Acute respiratory triage"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript A fresh draft for an acute respiratory pathway
const url = 'https://staging.cail.health/v1/plan-definitions/draft';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"acute-respiratory","version":"2.4.0","title":"Acute respiratory triage"}'
};

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

```go A fresh draft for an acute respiratory pathway
package main

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

func main() {

	url := "https://staging.cail.health/v1/plan-definitions/draft"

	payload := strings.NewReader("{\n  \"name\": \"acute-respiratory\",\n  \"version\": \"2.4.0\",\n  \"title\": \"Acute respiratory triage\"\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 A fresh draft for an acute respiratory pathway
require 'uri'
require 'net/http'

url = URI("https://staging.cail.health/v1/plan-definitions/draft")

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  \"name\": \"acute-respiratory\",\n  \"version\": \"2.4.0\",\n  \"title\": \"Acute respiratory triage\"\n}"

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

```java A fresh draft for an acute respiratory pathway
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://staging.cail.health/v1/plan-definitions/draft")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"acute-respiratory\",\n  \"version\": \"2.4.0\",\n  \"title\": \"Acute respiratory triage\"\n}")
  .asString();
```

```php A fresh draft for an acute respiratory pathway
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://staging.cail.health/v1/plan-definitions/draft', [
  'body' => '{
  "name": "acute-respiratory",
  "version": "2.4.0",
  "title": "Acute respiratory triage"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp A fresh draft for an acute respiratory pathway
using RestSharp;

var client = new RestClient("https://staging.cail.health/v1/plan-definitions/draft");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"acute-respiratory\",\n  \"version\": \"2.4.0\",\n  \"title\": \"Acute respiratory triage\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift A fresh draft for an acute respiratory pathway
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "acute-respiratory",
  "version": "2.4.0",
  "title": "Acute respiratory triage"
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://staging.cail.health/v1/plan-definitions/draft")! 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()
```