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

# Agent Versioning

> Version control for your agents — draft/published workflow, full snapshots, rollback, and environment promotion.

# Agent Versioning

thinnestAI gives you full version control over your agents. Every change you make stays in **draft** until you explicitly **publish** it. This means you can experiment freely without affecting live conversations.

## How It Works

```
┌──────────────────────────────────────────────────────┐
│                   Your Agent                          │
│                                                       │
│   DRAFT (editable)          PUBLISHED (frozen)        │
│   ┌─────────────────┐      ┌─────────────────┐      │
│   │ Instructions     │      │ Instructions     │      │
│   │ Model            │  ──► │ Model            │      │
│   │ Tools            │ Pub  │ Tools            │      │
│   │ Voice Config     │ lish │ Voice Config     │      │
│   │ Knowledge        │      │ Knowledge        │      │
│   │ Memory Config    │      │ Memory Config    │      │
│   └─────────────────┘      └─────────────────┘      │
│         ▲ You edit               ▲ Users talk to     │
└──────────────────────────────────────────────────────┘
```

1. **You edit the draft** — Change instructions, add tools, update the model, configure voice settings. Nothing goes live.
2. **You publish** — thinnestAI captures a complete snapshot of your agent's state and freezes it as the live version.
3. **Users interact with the published version** — All conversations use the frozen snapshot, not your in-progress edits.
4. **You can rollback anytime** — Restore any previous version instantly if something goes wrong.

## Draft vs Published

|                               | Draft             | Published              |
| ----------------------------- | ----------------- | ---------------------- |
| **What is it?**               | Your working copy | A frozen snapshot      |
| **Editable?**                 | Yes, always       | No — it's immutable    |
| **Used for live chat/voice?** | No                | Yes                    |
| **Created when?**             | Always exists     | When you click Publish |

When you first create an agent, it starts in **draft** mode. Users cannot interact with it until you publish it for the first time.

## What Gets Versioned

Every version captures a **complete snapshot** of your entire agent — not just the instructions:

| Panel              | Fields Captured                                              |
| ------------------ | ------------------------------------------------------------ |
| **Core Config**    | Name, model, instructions, agent type                        |
| **Tools**          | All enabled tools and their configurations                   |
| **Knowledge**      | Linked knowledge sources                                     |
| **Voice**          | STT/TTS provider, model, voice, speed, interruption settings |
| **Memory**         | Session settings, optimization, custom instructions          |
| **Publish/Widget** | Widget theme, domains, lead capture, suggested prompts       |
| **Graph/Workflow** | Node graph data, workflow steps, team members                |
| **Variables**      | Dynamic prompt variables and defaults                        |

This means rolling back to a previous version restores **everything** — not just the prompt.

## Using the Dashboard

### Publishing

1. Open your agent in the **Agent Studio**.
2. Make your changes across any panel (instructions, tools, voice, etc.).
3. Click the **Publish** button in the top-right header bar.
4. Optionally add a **change summary** (e.g., "Added FAQ tool and updated greeting").
5. Click **Publish Now**. Your agent is immediately live with the new version.

The Publish button reflects the current state:

* **Publish** — Agent has never been published. Click to go live.
* **Update Live** — Agent is published but has unpublished draft changes. A yellow dot indicator appears on the button.
* **Published** (green) — The live version matches your draft. No pending changes.

You'll also see a status badge next to the agent name in the header:

* **Draft** (orange) — Agent is in draft-only mode
* **Live** (green) — Agent is published and serving users

### Preview Changes Before Publishing

When your agent is already published and you've made edits, click the **Publish** button and then **Preview changes before publishing** to see a side-by-side diff of exactly what will change. Each modified field is shown with its old (red) and new (green) values.

### Unpublishing

To take an agent offline, click the **Publish** button, then click **Unpublish** at the bottom. The agent reverts to draft-only mode and stops serving the frozen version.

### Version History Panel

Open the **Versions** panel in the left sidebar to access the full version timeline:

* **Version list** — Every publish creates a version card showing the version label, change summary, environment, and timestamp. The currently live version is highlighted with a green "Live" badge.
* **Save Checkpoint** — Create a manual snapshot of your current draft without publishing. Useful before experimenting with risky changes.
* **Draft vs Live** — One-click comparison showing exactly what differs between your current draft and the published version.
* **Compare any two versions** — Click the **Compare** button, then select two version cards to see a field-by-field diff.
* **View snapshot** — Expand any version card and click **View** to see the complete frozen JSON snapshot.
* **Rollback** — Expand any version card and click **Rollback** to restore that version. A backup of the current state is saved automatically before the rollback, and the restored state is auto-published.

## Publishing via the API

### Publish Current Draft

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/{agent_id}/publish \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "change_summary": "Added FAQ tool and updated greeting"
  }'
```

Response:

```json theme={null}
{
  "success": true,
  "status": "published",
  "version_id": 12,
  "version_number": 5,
  "version_label": "v5"
}
```

### Unpublish (Revert to Draft-Only)

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/{agent_id}/unpublish \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

This stops serving the frozen version. The agent will fall back to draft mode.

### Check Publish Status

```bash theme={null}
curl https://api.thinnest.ai/agents/{agent_id}/status \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

Response:

```json theme={null}
{
  "status": "published",
  "published_version_id": 12,
  "last_published_at": "2026-03-07T14:30:00",
  "has_unpublished_changes": true,
  "changed_fields": ["instructions", "tools"]
}
```

The `has_unpublished_changes` field tells you whether the draft differs from the published version. The `changed_fields` array shows which panels have been modified.

## Version History

Every time you publish, a new version is created automatically. You can view the full history in the **Versions** panel in the Agent Studio sidebar, or query it via the API.

### List Versions (API)

```bash theme={null}
curl https://api.thinnest.ai/agents/{agent_id}/versions \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

Response:

```json theme={null}
{
  "versions": [
    {
      "id": 12,
      "version_number": 5,
      "version_label": "v5",
      "name": "Support Agent",
      "environment": "production",
      "is_active": true,
      "created_by": "auth0|abc123",
      "created_at": "2026-03-07T14:30:00",
      "change_summary": "Added FAQ tool and updated greeting"
    },
    {
      "id": 11,
      "version_number": 4,
      "version_label": "v4",
      "name": "Support Agent",
      "environment": "production",
      "is_active": false,
      "created_by": "auth0|abc123",
      "created_at": "2026-03-06T10:15:00",
      "change_summary": "Updated voice to use faster TTS"
    }
  ]
}
```

### Get Version Details

Retrieve the full snapshot of a specific version:

```bash theme={null}
curl https://api.thinnest.ai/agents/{agent_id}/versions/{version_id} \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

The response includes the complete `snapshot` object with all config, tools, sources, voice settings, and more.

### Save a Manual Checkpoint

You can create a version snapshot without publishing — useful as a checkpoint before experimenting. In the dashboard, click **Save Checkpoint** in the Versions panel. Via the API:

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/{agent_id}/versions \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "change_summary": "Checkpoint before tool experiment",
    "version_label": "pre-experiment",
    "environment": "development"
  }'
```

## Rollback

If a published version causes issues, you can instantly rollback to any previous version — from the dashboard or the API.

In the dashboard, go to the **Versions** panel, expand the version you want to restore, and click **Rollback**. You'll be asked to confirm before the rollback executes.

### Rollback via API

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/{agent_id}/versions/{version_id}/rollback \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

What happens during a rollback:

1. A **backup** of your current state is saved automatically (so you can undo the rollback).
2. The target version's complete snapshot is **restored** onto your agent — instructions, tools, voice, knowledge, everything.
3. The restored state is **auto-published** so it goes live immediately.

```json theme={null}
{
  "success": true,
  "message": "Rolled back to version 3",
  "agent_id": "ag_abc123"
}
```

## Comparing Versions

You can compare versions both in the dashboard and via the API. In the dashboard, use the **Compare** button in the Versions panel to select two versions, or click **Draft vs Live** to see pending changes. The diff viewer highlights each changed field with before/after values.

### Diff Two Versions (API)

Compare any two versions to see exactly what changed:

```bash theme={null}
curl https://api.thinnest.ai/agents/{agent_id}/versions/{version_a}/diff/{version_b} \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

Response:

```json theme={null}
{
  "version_a": { "id": 11, "version_number": 4 },
  "version_b": { "id": 12, "version_number": 5 },
  "changes": {
    "instructions": {
      "old": "You are a support agent...",
      "new": "You are a friendly support agent..."
    },
    "tools": {
      "old": [{"name": "email", "type": "email"}],
      "new": [{"name": "email", "type": "email"}, {"name": "faq", "type": "knowledge_search"}]
    }
  },
  "has_changes": true
}
```

### Diff Draft vs Published (API)

See what will change when you next publish:

```bash theme={null}
curl https://api.thinnest.ai/agents/{agent_id}/diff-draft \
  -H "Authorization: Bearer $THINNESTAI_API_KEY"
```

This is especially useful before publishing to confirm you're deploying exactly what you intend.

## Environment Promotion

For teams that use staging environments, you can promote a version from one environment to another:

```bash theme={null}
curl -X POST https://api.thinnest.ai/agents/{agent_id}/versions/{version_id}/promote \
  -H "Authorization: Bearer $THINNESTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version_id": 12,
    "target_environment": "production"
  }'
```

Supported environments: `development`, `staging`, `production`.

The promotion flow:

```
development  ──►  staging  ──►  production
  (draft)        (testing)      (live users)
```

## Best Practices

* **Publish with summaries** — Always add a change summary so your team can understand what changed in each version.
* **Create checkpoints before experiments** — Click **Save Checkpoint** in the Versions panel (or use the API) before trying risky changes.
* **Preview before publishing** — Use **Draft vs Live** or the **Preview changes** link in the publish popover to verify only your intended changes go live.
* **Don't skip rollback** — If a new version causes issues, rollback immediately from the Versions panel rather than trying to fix forward under pressure.
* **Review version history regularly** — The Versions panel acts as an audit trail for your agent's evolution.
* **Watch the publish button indicator** — A yellow dot on the Publish button means you have unpublished changes that aren't live yet.

## API Reference

| Method | Endpoint                               | Description                                |
| ------ | -------------------------------------- | ------------------------------------------ |
| `POST` | `/agents/{id}/publish`                 | Publish current draft as live version      |
| `POST` | `/agents/{id}/unpublish`               | Revert to draft-only mode                  |
| `GET`  | `/agents/{id}/status`                  | Get publish status and unpublished changes |
| `GET`  | `/agents/{id}/versions`                | List all versions                          |
| `POST` | `/agents/{id}/versions`                | Create a manual checkpoint                 |
| `GET`  | `/agents/{id}/versions/{vid}`          | Get full version snapshot                  |
| `POST` | `/agents/{id}/versions/{vid}/rollback` | Rollback to a version                      |
| `POST` | `/agents/{id}/versions/{vid}/promote`  | Promote to another environment             |
| `GET`  | `/agents/{id}/versions/{a}/diff/{b}`   | Compare two versions                       |
| `GET`  | `/agents/{id}/diff-draft`              | Compare draft vs published                 |