Versions - Cartesia Docs

Each effective agent configuration change creates an immutable version. New calls use the latest version, while an active call stays on the version it started with. There is no separate publish step. Saving a configuration change publishes it immediately.

Version contents

A version contains a complete configuration snapshot and creation metadata:

{
  "id": "av_7Hq2mXbK9cLdNfPzR3tWvE",
  "description": "Move support to a stronger model",
  "created_at": "2026-08-14T12:34:56.789Z",
  "created_by": "user_123",
  "config": { /* complete agent configuration */ }
}

Include version_description in an agent update to record why the configuration changed. Metadata-only updates, such as changing the agent’s name, do not create versions.

Browse version history

GET /v1/agents/{agent_id}/versions lists versions from newest to oldest. GET /v1/agents/{agent_id}/versions/{version_id} returns one version with its complete configuration.

Restore a version

Read the version’s config, then send it through PATCH /v1/agents/{agent_id}. This creates a new version instead of rewriting history. Cartesia validates the configuration again. If it references a resource that has since been deleted, replace that reference before restoring it.

Referenced resources

Versions store tool and voice IDs, not copies of those resources. Editing a tool affects every agent that references it without creating an agent version. To avoid changing the behavior of earlier versions, create a new tool and attach it instead.

​Version contents

​Browse version history

​Restore a version

​Referenced resources

Version contents

Browse version history

Restore a version

Referenced resources