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

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:

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

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:

{
  "success": true,
  "status": "published",
  "version_id": 12,
  "version_number": 5,
  "version_label": "v5"
}

Unpublish (Revert to Draft-Only)

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

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

Response:

{
  "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)

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

Response:

{
  "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:

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:

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

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.

{
  "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:

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

Response:

{
  "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:

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:

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