Create a draft

POST

agents

{agent_id}

drafts

Create Draft

curl --request POST \
  --url https://api.vocily.ai/v1/agents/{agent_id}/drafts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_version": 4,
  "label": "Shorter greeting"
}
'

import requests

url = "https://api.vocily.ai/v1/agents/{agent_id}/drafts"

payload = {
    "from_version": 4,
    "label": "Shorter greeting"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({from_version: 4, label: 'Shorter greeting'})
};

fetch('https://api.vocily.ai/v1/agents/{agent_id}/drafts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/agents/{agent_id}/drafts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from_version' => 4,
    'label' => 'Shorter greeting'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.vocily.ai/v1/agents/{agent_id}/drafts"

	payload := strings.NewReader("{\n  \"from_version\": 4,\n  \"label\": \"Shorter greeting\"\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(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vocily.ai/v1/agents/{agent_id}/drafts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from_version\": 4,\n  \"label\": \"Shorter greeting\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/agents/{agent_id}/drafts")

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  \"from_version\": 4,\n  \"label\": \"Shorter greeting\"\n}"

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

{
  "version": 2,
  "version_id": "00000009-0000-4000-8000-000000000009",
  "is_published": false,
  "is_live": false,
  "label": "Second",
  "notes": null,
  "base_version": 0,
  "document_revision": 1,
  "blocked_reasons": [],
  "inbound_phone": null,
  "inbound_whatsapp": null,
  "created_at": "2026-09-16T19:38:04.119386Z",
  "published_at": null
}

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

{ "from_version": 4, "label": "Shorter greeting" }

Omit from_version to branch from the live version. An agent may hold as many drafts as you like — each owns its own copy of the configuration, so editing one never disturbs another.

You rarely need this. Updating an agent branches a draft for you when the newest version is published. Call this when you want several drafts in flight at once.

Authorizations

Authorization

string

header

required

Your API key as a Bearer token, e.g. Authorization: Bearer vk_….

Path Parameters

agent_id

string

required

The agent's id, as GET /v1/agents returns it.

Body

application/json

POST /v1/agents/{id}/drafts.

Either spelling of "which version do I branch from" is accepted: from_version, the number you already hold, or base_version_id, its uuid. An unknown field is refused here rather than deeper in, so a typo reads like every other refused body on this surface.

from_version

integer | null

The version to branch from, by number — e.g. 4. Omit to branch from the live version, or from the newest one if nothing is live yet.

base_version_id

string | null

The same choice by uuid. from_version is the friendlier one: a number is what a version is called everywhere else.

label

string | null

A short name for the draft. V<n> is already its identity, so this is description rather than a name.

Maximum string length: 80

Response

The new draft, branched from the version you named.

One version in an agent's history.

Versions are identified by NUMBER: it is what every version read returns and what ?version= and /versions/{n} take.

version

integer

required

This version's number — what you pass in /versions/{n}.

version_id

string

required

This version's uuid. Published because POST /v1/calls pins a call with agent_version_id, which takes a uuid rather than a number.

is_published

boolean

required

True once frozen. Configuration can never be edited again; label and notes still can.

is_live

boolean

required

True if this is the version answering calls right now.

document_revision

integer

required

This version's edit counter. Send it as If-Match to make a write conditional.

created_at

string<date-time>

required

When this version was created (UTC, ISO 8601).

label

string | null

Short name for this version.

notes

string | null

Longer free text about this version.

base_version

integer | null

Which version this one was branched from, by NUMBER — null for the agent's first.

blocked_reasons

string[]

Why this version cannot be made live, if it cannot — e.g. it pins a retired model. Check it before offering a deploy button, so the button never fails on click.

inbound_phone

string | null

The phone number this version will answer on once it is made live. Inert until then.

inbound_whatsapp

string | null

The WhatsApp number this version will answer on once it is made live. Inert until then.

published_at

string<date-time> | null

When it was frozen. null while it is still a draft.

Create Draft

curl --request POST \
  --url https://api.vocily.ai/v1/agents/{agent_id}/drafts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from_version": 4,
  "label": "Shorter greeting"
}
'

import requests

url = "https://api.vocily.ai/v1/agents/{agent_id}/drafts"

payload = {
    "from_version": 4,
    "label": "Shorter greeting"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({from_version: 4, label: 'Shorter greeting'})
};

fetch('https://api.vocily.ai/v1/agents/{agent_id}/drafts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.vocily.ai/v1/agents/{agent_id}/drafts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'from_version' => 4,
    'label' => 'Shorter greeting'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.vocily.ai/v1/agents/{agent_id}/drafts"

	payload := strings.NewReader("{\n  \"from_version\": 4,\n  \"label\": \"Shorter greeting\"\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(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.vocily.ai/v1/agents/{agent_id}/drafts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"from_version\": 4,\n  \"label\": \"Shorter greeting\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.vocily.ai/v1/agents/{agent_id}/drafts")

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  \"from_version\": 4,\n  \"label\": \"Shorter greeting\"\n}"

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

{
  "version": 2,
  "version_id": "00000009-0000-4000-8000-000000000009",
  "is_published": false,
  "is_live": false,
  "label": "Second",
  "notes": null,
  "base_version": 0,
  "document_revision": 1,
  "blocked_reasons": [],
  "inbound_phone": null,
  "inbound_whatsapp": null,
  "created_at": "2026-09-16T19:38:04.119386Z",
  "published_at": null
}

{
  "detail": "Invalid API key",
  "code": "UNAUTHORIZED"
}

{
  "detail": {
    "code": "validation_error",
    "message": "<string>",
    "errors": [
      {
        "field": "<string>",
        "message": "<string>",
        "type": "<string>"
      }
    ]
  },
  "code": "VALIDATION_ERROR"
}

{
  "code": "rate_limited"
}

Calls

Chats

Phone Numbers

Knowledge Bases

Files

Agents

Speech

Catalogues

Integrations

Custom Analysis

Memory

Widget

Webhooks

Create a draft

Authorizations

Path Parameters

Body

Response