Skip to main content
POST
Create Agent Version

Overview

Validates a full configuration snapshot and saves it as an immutable version on the agent’s dev timeline, or on an open branch when branch_id is set. Saving does not deploy anything; staging and production pin a version through Publish Agent and Promote Agent. Read the current head with Get Latest Agent Version. Requires an admin, owner, operator, or prompter role.

Headers

string
required
Your API key for authentication.

Path Parameters

string
required
The agent’s unique identifier.

Body Parameters

object
required
The complete agent configuration: behavior, settings, contact, and optionally knowledge. Structural problems return 400 INVALID_SNAPSHOT with one error entry per problem (up to 20). A snapshot larger than 2,097,152 bytes when serialized is rejected outright.
The root behavior graph, shaped { "nodes": [], "edges": [] }.Each node needs a string id that is unique within its flow, a position of { "x": number, "y": number }, and a data object. type names the node kind (for example start, scenario, complex-scenario, auth). Container nodes carry a nested data.flow with the same { nodes, edges } shape, validated recursively; flows may nest at most 10 levels deep.Each edge needs string id, source, and target values, and source and target must reference nodes in the same flow.
Agent-wide configuration. displayName and systemPrompt must be strings. The remaining keys the dashboard writes (voice, languages, enableMemory, interruptionSensitivity, backgroundNoise, voiceCall, webChat, requestData, metadata, color, and others) are stored as sent and applied at call time.guardrails is optional. When present it must be an array (not null). Each entry has a unique string id, a kind, and an actions array whose items are { "type": "end_call" }, { "type": "transfer", "phoneNumber": "..." }, or { "type": "move_to_node", "nodeId": "..." }. Accepted kinds:
  • tcpa:ai_disclosure, tcpa:recording_disclosure, tcpa:self_introduction: also require endSeconds, an integer from 1 to 600.
  • tcpa:opt_out: no extra fields.
  • custom: requires a non-empty name, a string description, and a non-empty prompt. At most 5 custom guardrails per agent.
Each built-in kind may appear once. A move_to_node target must be a step the agent can actually move to. Custom guardrails require an enterprise plan: adding one that is not already saved on this agent returns 403 ENTERPRISE_REQUIRED. Custom guardrails already saved keep running and can still be edited.
inboundNumbers must be an array of phone number strings routed to this agent, or a single {{env.KEY}} reference string that resolves to an environment variable at call time.
When present, must be { "kbIds": string[] }, the knowledge base IDs the agent retrieves against on every call. null is rejected; omit the key instead. Order carries no meaning.
string
Display name for the version. Leading and trailing whitespace is trimmed; an empty or whitespace-only value is treated as no name. A named version is always written as a new row and is never pruned.
string
Save onto an open branch instead of the dev timeline. Returns 404 BRANCH_NOT_FOUND if the branch is not open or does not belong to this agent.
boolean
default:"false"
Mark this as an editor background save. While the timeline’s head is an unnamed autosave that nothing references (no environment pin, deployment, branch base, experiment, or check run), the save rewrites that head in place and increments its revision instead of appending. The response then carries version metadata only, without org_id or snapshot. Any value other than true is treated as false.
string | null
Compare-and-set guard. The version ID you believe is the current head of the timeline you are saving onto; send null to assert the timeline is empty. On a branch with no saves of its own, the head is the branch’s base version. If the real head differs, nothing is written and the response is 409 STALE_HEAD with the real head’s ID and revision at the top level of the body as head_version_id and head_revision. Omit the field to skip the check.
integer
Second half of the compare-and-set: the head’s revision as you last saw it. An in-place autosave keeps the head’s ID stable, so parent_version_id alone cannot detect a concurrent autosave from another editor; the revision can. Checked only when parent_version_id matches. Non-integer values are ignored. Omit to skip.

Response

Returns 201 on success. A manual save returns the full version row. An autosave returns the same object without org_id and snapshot.
object
The saved version.
null | array
null on success, or a list of error objects if the request failed.

Docs for agents: llms.txt