> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versions

> Inspect configuration history and restore an earlier version.

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:

```jsonc theme={null}
{
  "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`](/api-reference/agents/versions/list) lists versions from newest to oldest. [`GET /v1/agents/{agent_id}/versions/{version_id}`](/api-reference/agents/versions/get) returns one version with its complete configuration.

## Restore a version

Read the version's `config`, then send it through [`PATCH /v1/agents/{agent_id}`](/api-reference/agents/update). 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.