Agent versions

Every agent you edit is a draft. Publishing freezes a copy of it as a numbered version that never changes. You can then pin a phone number or a call to that version, so a later edit to the draft cannot change what callers hear.

Publishing is optional. If you never publish, every call runs the draft, as it always has.

Draft and published versions

• The draft is version 0. It is the agent you create and update at Create agent. It is not a stored version, so it does not appear in the version list.
• Published versions start at 1 and count up for each agent. Nothing edits or deletes them.
• A version is a copy of the agent's settings, its functions and its MCP servers. Editing a function later does not change a version that already copied it.
• Secrets are never returned. Signing secrets and MCP auth tokens are replaced by has_ flags.

Publish a version

POST /v1/agents/AGENT_ID/versions freezes the agent as it is now. The body is optional. title (up to 200 characters) and description (up to 2000) are labels for people; the version number is its identity.

curl https://api.dialgem.com/v1/agents/AGENT_ID/versions \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Adds the refund flow" }'

The response is 201 with the new version, including its full snapshot. Two errors are specific to publishing:

• 409 with simulation_required: a simulation suite requires the draft to pass first. Run the suite, or change its publish gate. When the gate is set to warn instead, the publish succeeds and the response carries a warnings array.
• 409 with version_conflict: two publishes ran at the same moment. Retry.

List and inspect versions

GET /v1/agents/AGENT_ID/versions returns published versions, newest first, as versions plus has_more. Each item has version, title, description, published_at, published_by, function_count and mcp_server_count, but not the snapshot.

GET /v1/agents/AGENT_ID/versions/VERSION returns one version with its snapshot: config, functions and mcp_servers. Asking for 0 or a number that was never published returns 404. To read the draft, fetch the agent itself.

curl https://api.dialgem.com/v1/agents/AGENT_ID/versions/VERSION \
  -H "X-API-Key: $DIALGEM_API_KEY"

Pin a call to a version

Calls take an agent_version field:

Web calls accept it on POST /v1/calls/web, and outbound and registered calls accept it on POST /v1/calls/outbound and POST /v1/calls/register (see Calls).

curl https://api.dialgem.com/v1/calls/web \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "AGENT_ID", "agent_version": "latest_published" }'

An unknown version number is rejected with 422 before the call starts. The call record always stores the concrete number that ran, never the word latest_published, so you can read back exactly which version handled a call.

Pin a phone number

Phone numbers have inbound_agent_version and outbound_agent_version, which take the same values. Set them when you create or update a number, or through the assign route. See Inbound routing.

curl -X PATCH https://api.dialgem.com/v1/phone-numbers/NUMBER_ID \
  -H "X-API-Key: $DIALGEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "inbound_agent_version": "latest_published" }'

With "latest_published" on a number, each new publish takes effect without touching the number.

Roll back

There is no rollback route, because versions never change. To roll back, point at an older version: set the number's inbound_agent_version to the earlier number, or pass that number in agent_version on new calls. To start editing from an old version, read it with the call above and apply its settings to the draft.

What editing the draft does to running calls

A call reads its version once, when it starts. Editing the draft never alters a published version, so calls pinned to a number are unaffected. Pin production traffic to a number and keep 0 for testing; use "latest_published" only when you want each publish to go live at once.

If a pinned version cannot be found when a call starts, the call is refused rather than silently running the draft.

Next: write the draft in Prompt agents or Flow agents, and see every field under Agents.