> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vocily.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a draft
> Branch a new draft from any version.
```json theme={"dark"}
{ "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](/developers/agents/update) branches a draft for you when
the newest version is published. Call this when you want **several** drafts in flight at once.
## OpenAPI
````yaml developers/openapi.json POST /v1/agents/{agent_id}/drafts
openapi: 3.1.0
info:
title: Vocily API
description: >-
Public REST API for Vocily. Build and configure an agent, publish a version
and put it live, place outbound calls, and read back calls, chats and what
the agent remembered. Authenticate with a workspace API key as a Bearer
token.
Some things stay in the dashboard, by design: creating an API key, buying or
connecting a phone number, setting an agent's webhook URL, connecting
WhatsApp and its templates, building HTTP tools, and running batch
campaigns.
version: v1
servers:
- url: https://api.vocily.ai
description: Production
security: []
paths:
/v1/agents/{agent_id}/drafts:
post:
tags:
- agent-versions
summary: Create Draft
description: >-
Branch a new draft from any version. An agent may hold as many drafts as
you like, and editing one never disturbs another.
Name the base by version number — `{"from_version": 4}`. Omit it to
branch from the live version.
operationId: create_draft_v1_agents__agent_id__drafts_post
parameters:
- name: agent_id
in: path
required: true
schema:
type: string
title: Agent Id
description: The agent's id, as `GET /v1/agents` returns it.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublicDraftRequest'
example:
from_version: 4
label: Shorter greeting
responses:
'201':
description: The new draft, branched from the version you named.
content:
application/json:
schema:
$ref: '#/components/schemas/PublicVersionSummary'
example:
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
'401':
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
detail: Invalid API key
code: UNAUTHORIZED
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
'429':
description: Rate limit exceeded — honor `Retry-After`.
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
example:
code: rate_limited
security:
- bearerAuth: []
components:
schemas:
PublicDraftRequest:
properties:
from_version:
anyOf:
- type: integer
- type: 'null'
title: From Version
description: >-
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:
anyOf:
- type: string
- type: 'null'
title: Base Version Id
description: >-
The same choice by uuid. `from_version` is the friendlier one: a
number is what a version is called everywhere else.
label:
anyOf:
- maxLength: 80
type: string
- type: 'null'
title: Label
description: >-
A short name for the draft. `V` is already its identity, so this
is description rather than a name.
additionalProperties: false
type: object
title: PublicDraftRequest
description: >-
`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.
PublicVersionSummary:
additionalProperties: false
description: >-
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.
properties:
version:
description: This version's number — what you pass in `/versions/{n}`.
title: Version
type: integer
version_id:
description: >-
This version's uuid. Published because `POST /v1/calls` pins a call
with `agent_version_id`, which takes a uuid rather than a number.
title: Version Id
type: string
is_published:
description: >-
True once frozen. Configuration can never be edited again; `label`
and `notes` still can.
title: Is Published
type: boolean
is_live:
description: True if this is the version answering calls right now.
title: Is Live
type: boolean
label:
anyOf:
- type: string
- type: 'null'
default: null
description: Short name for this version.
title: Label
notes:
anyOf:
- type: string
- type: 'null'
default: null
description: Longer free text about this version.
title: Notes
base_version:
anyOf:
- type: integer
- type: 'null'
default: null
description: >-
Which version this one was branched from, by NUMBER — `null` for the
agent's first.
title: Base Version
document_revision:
description: >-
This version's edit counter. Send it as `If-Match` to make a write
conditional.
title: Document Revision
type: integer
blocked_reasons:
description: >-
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.
items:
type: string
title: Blocked Reasons
type: array
inbound_phone:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
The phone number this version will answer on once it is made live.
Inert until then.
title: Inbound Phone
inbound_whatsapp:
anyOf:
- type: string
- type: 'null'
default: null
description: >-
The WhatsApp number this version will answer on once it is made
live. Inert until then.
title: Inbound Whatsapp
created_at:
description: When this version was created (UTC, ISO 8601).
format: date-time
title: Created At
type: string
published_at:
anyOf:
- type: string
format: date-time
- type: 'null'
default: null
description: When it was frozen. `null` while it is still a draft.
title: Published At
required:
- version
- version_id
- is_published
- is_live
- document_revision
- created_at
title: PublicVersionSummary
type: object
ApiError:
type: object
description: >-
Error envelope. `code` is derived from the HTTP status, so branch on it
for the CLASS of failure; the specific reason is `detail.code`. Every
public refusal carries both.
properties:
detail:
type: object
description: >-
The reason. `code` is the domain reason (e.g. `call_not_found`) and
`message` is a sentence safe to log. On a `422` it also carries
`errors[]`, one entry per rejected field — see
`HTTPValidationError`.
properties:
code:
type: string
example: call_not_found
message:
type: string
example: Call not found
required:
- code
- message
code:
type: string
description: Derived from the HTTP status, not the domain reason.
example: NOT_FOUND
HTTPValidationError:
type: object
title: HTTPValidationError
description: >-
A request the API could not read: a field of the wrong type, out of
range, missing, or one we do not accept. Same envelope as every other
error.
properties:
detail:
type: object
description: >-
What was wrong, as `code`, a one-line `message`, and every offending
field in `errors`.
required:
- code
- message
- errors
properties:
code:
type: string
enum:
- validation_error
message:
type: string
description: >-
The first problem in one line, with a count of the rest — e.g.
`model.temperature: Input should be less than or equal to 2 (and
1 more)`.
errors:
type: array
items:
$ref: '#/components/schemas/ValidationError'
description: >-
One entry per offending field. **Every problem is reported at
once**, not just the first, so a malformed body needs one round
trip to fix rather than one per field.
code:
type: string
enum:
- VALIDATION_ERROR
description: Derived from the HTTP status, as on every error.
ValidationError:
type: object
title: ValidationError
required:
- field
- message
- type
properties:
field:
type: string
description: >-
The offending field as a path from the root of your request —
`voice.speed`, `variables[0].key`, or `query.limit` for a query
parameter. **This is the field to read.**
message:
type: string
description: What is wrong with it, in plain language.
type:
type: string
description: >-
A stable machine code for the kind of failure, e.g.
`extra_forbidden` for a field we do not accept, `missing` for a
required one, or `less_than_equal` for a number out of range. Switch
on this rather than on `message`, which may be reworded.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.'
````