Versions

An agent has a draft you edit and a published version that live traffic runs. Every write — dashboard, API, MCP server or CoPilot — lands on the draft; nothing reaches a caller until you publish.

	Draft	Published version
What it is	One mutable `config` per agent	An immutable numbered snapshot per publish (`1`, `2`, … never reused)
Who runs it	Only calls that ask for `agent_version: "draft"`	Inbound and outbound calls, batches, chats
Changed by	`PATCH /v1/agents/{agent_id}`	Publishing again, or rolling back
Tool attachments	`tool_version: null` — track the tool’s current published version	Pinned to the tool version live at publish

GET /v1/agents/{agent_id} returns the draft config, published_version (null if never published), published_at, updated_at and versions. An updated_at later than published_at means the draft has unpublished edits.

Publishing

POST /v1/agents/{agent_id}/publish runs validation, freezes the draft as the next version and makes it live. It returns version, published_at and warnings; a failure is a 400 listing every error and publishes nothing. Publishing and validating need the editor role.

curl -X POST https://api.talqing.com/v1/agents/9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704/publish \
  -H "Authorization: Bearer $TALQING_API_KEY"

const published = await talqing.agents.publish({
  agent_id: "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
});
console.log(published.version, published.warnings);

published = talqing.agents.publish("9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704")
print(published["version"], published["warnings"])

To try an edit without publishing, start a call with agent_version: "draft" — see per-call configuration.

Publishing pins tool versions

Publishing an agent records, for each attached tool, lifecycle hook and task, the version live at that moment. Republishing the tool afterwards does not change what calls run: publish the agent again to pick up the new tool version.

A published version’s tools entries read {"tool_id": "…", "tool_version": 3}; the draft’s read "tool_version": null. The dashboard’s version diff lists per-tool pins (v3 → v4). Attaching a tool that has never been published is refused (tool '…' has no published version - publish it before attaching). So the order is always:

# 1. publish the tool
curl -X POST https://api.talqing.com/v1/tools/$TOOL_ID/publish \
  -H "Authorization: Bearer $TALQING_API_KEY" -H "Content-Type: application/json" \
  -d '{"changelog": "first version"}'
# 2. attach it (tools is a list, sent whole)
curl -X PATCH https://api.talqing.com/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $TALQING_API_KEY" -H "Content-Type: application/json" \
  -d "{\"config\": {\"tools\": [{\"tool_id\": \"$TOOL_ID\"}]}}"
# 3. publish the agent
curl -X POST https://api.talqing.com/v1/agents/$AGENT_ID/publish \
  -H "Authorization: Bearer $TALQING_API_KEY"

Not pinned: an MCP integration’s allowed_tools (read live) and FAQ content (live; a version freezes only which FAQs are attached).

History and diff

GET /v1/agents/{agent_id} → versions: every publish, newest first, with version, published_at and published_by (email). The list endpoint omits it.
GET /v1/agents/{agent_id}/versions/{version} → that version’s full frozen config, tool pins included.
Dashboard: Version history in the agent editor compares any two versions or the draft, grouped by section, with per-tool pins.

Rollback

POST /v1/agents/{agent_id}/versions/{version}/rollback:

Creates no new version — published_version points back at the old one.
Replaces the draft with that version’s config; unpublished edits are lost.
The restored draft is unpinned: publishing it again pins the tools’ current versions, not the old ones.
Sets updated_at to that version’s published_at, so it does not read as having unpublished edits.
Is refused if that version cannot answer a phone number the agent is assigned to (for example, a required variable with no default).

Rollback takes effect immediately for every new call. Calls in progress finish on the version they started with.

When a publish takes effect

Surface	Picks up a new publish
A call in progress	Never
New inbound call	Immediately — a number points at the agent, not a version; no re-assign needed
New outbound or web call	Immediately, unless the request pinned `agent_version`
Running batch	Every dial after the publish
Open chat	Next message
Handoff by `agent_id`	Immediately (latest published version)

A session started with a pinned agent_version, an agent_override or an inline agent keeps what it started with.

Deleting an agent

DELETE /v1/agents/{agent_id} deletes its versions permanently; past calls keep transcripts but no longer show the config they ran. It is refused with a 409, naming each blocker, while anything would still route to it: an enabled phone number, stream connection or integration trigger, an unfinished call batch, or another agent or tool that hands off to it.

Validation

Why a publish is refused.

Publishing tools

Tool versions from the tool side.

Get started

Build

Guides

Publishing

Publishing pins tool versions

History and diff

Rollback

When a publish takes effect

Deleting an agent

Next

Validation

Publishing tools

​Publishing

​Publishing pins tool versions

​History and diff

​Rollback

​When a publish takes effect

​Deleting an agent

​Next

Validation

Publishing tools

Publishing

Publishing pins tool versions

History and diff

Rollback

When a publish takes effect

Deleting an agent

Next