Every change to a prompt creates a new immutable version with complete history. Labels act as named pointers to versions, enabling instant deployment, safe rollbacks, and environment-based release management—all without code changes.

How Version Control Works

Understanding the lifecycle of versions and labels:

Automatic version creation

When you create a prompt with a new name, ABV creates version 1. When you create another prompt with the same name (via UI, SDK, or API), ABV creates version 2 instead of overwriting version 1.Version numbering: Incremental integers (1, 2, 3, 4…) assigned automatically based on creation order.Immutability: Once created, a version’s content, config, and metadata never change. This ensures:

Reproducibility: Fetching version 1 always returns identical content
Safe rollbacks: Previous versions are always available
Audit trails: Complete history of changes with timestamps and creators

Retention: All versions are retained indefinitely unless explicitly deleted.

Label assignment and management

Labels are named pointers to specific versions. Think of labels as Git branches or tags pointing to commits.Built-in labels:

production: Default label fetched when no label is specified in SDK calls
latest: Automatically updated to point to the most recently created version

Custom labels: Create any labels for your workflow:

Environment labels: staging, development, qa
Tenant labels: tenant-acme, tenant-contoso
A/B test labels: variant-a, variant-b, control, experiment
Geographic labels: us-region, eu-region

Multiple labels per version: A version can have multiple labels simultaneously (e.g., version 3 might have both production and stable).Label assignment:

Assign labels when creating prompts
Reassign labels to different versions via UI or API
Remove labels from versions

Fetching prompts by label or version

Your application fetches prompts using labels (for deployment management) or version numbers (for debugging or specific version testing).Fetching by label (recommended for production):

# Fetch production version (default behavior)
prompt = abv.get_prompt("movie-critic")

# Fetch staging version for testing
staging_prompt = abv.get_prompt("movie-critic", label="staging")

# Fetch latest version
latest_prompt = abv.get_prompt("movie-critic", label="latest")

Fetching by version (for debugging or specific version testing):

# Fetch specific version for comparison
v1 = abv.get_prompt("movie-critic", version=1)
v2 = abv.get_prompt("movie-critic", version=2)

Client-side caching: SDKs cache prompts locally for zero-latency fetches while background processes keep the cache synchronized with ABV. Label changes propagate automatically.

Deployment via label reassignment

Deploy new prompt versions by reassigning labels—no code changes, no CI/CD, no application restarts.Deployment workflow:

Create new prompt version (version 4)
Assign staging label to version 4 for testing
Test in staging environment (fetches staging label)
After validation, reassign production label from version 3 to version 4 in ABV UI
Production traffic immediately uses version 4

Instant deployment: Label reassignment takes effect immediately. Next SDK fetch (or cache refresh) returns the new version.Zero downtime: No application restarts or deployments required.

Rollback to previous versions

If a new prompt version causes issues, roll back by reassigning the production label to the previous version.Rollback workflow:

Notice issues with version 4 in production
Open ABV UI, navigate to prompt
Reassign production label from version 4 back to version 3
Production traffic immediately reverts to version 3

Rollback time: Seconds, not minutes or hours.Complete history: All versions remain available for future reference or re-deployment.

Assigning and Managing Labels

Labels can be managed via UI, SDK, or API:

Via ABV UI (Recommended for Deployment)

The ABV UI provides visual label management for non-technical team members.Steps:

Navigate to Prompts in the ABV dashboard
Select the prompt you want to manage
View all versions in the version history panel
For each version, see current labels and add/remove labels via dropdown
Reassign labels by removing from one version and adding to another

When to use: Deploying to production, managing staging/development environments, team collaboration scenarios where product managers control deployments.

Python SDK

Assign labels when creating prompts or update labels on existing versions.Assign labels when creating:

from abvdev import ABV

abv = ABV(
    api_key="sk-abv-...",
    host="https://app.abv.dev",
)

# Create prompt with production label
abv.create_prompt(
    name="movie-critic",
    type="text",
    prompt="As a {{criticlevel}} movie critic, do you like {{movie}}?",
    labels=["production", "stable"],  # Assign multiple labels
)

Update labels on existing versions:

# Reassign labels to version 1
abv.update_prompt(
    name="movie-critic",
    version=1,
    new_labels=["production", "rollback-safe"],  # Replace existing labels
)

# This removes all previous labels and assigns new ones

When to use: Automated deployment pipelines, infrastructure-as-code workflows, CI/CD integration.

JavaScript/TypeScript SDK

Assign labels when creating prompts or update labels on existing versions.Environment setup:

npm install @abvdev/client dotenv

.env

ABV_API_KEY=sk-abv-...
ABV_BASEURL=https://app.abv.dev  # US region
# ABV_BASEURL=https://eu.app.abv.dev  # EU region

Assign labels when creating:

import { ABVClient } from "@abvdev/client";
import dotenv from "dotenv";
dotenv.config();

const abv = new ABVClient();

async function main() {
  await abv.prompt.create({
    name: "movie-critic",
    type: "text",
    prompt: "As a {{criticlevel}} critic, do you like {{movie}}?",
    labels: ["production", "stable"],  // Assign multiple labels
  });
}

main();

Update labels on existing versions:

async function main() {
  await abv.prompt.update({
    name: "movie-critic",
    version: 1,
    newLabels: ["production", "rollback-safe"],  // Replace existing labels
  });
}

main();

When to use: Node.js deployment automation, TypeScript-based infrastructure, JavaScript CI/CD pipelines.

Fetching Prompts by Label or Version

Choose the appropriate fetching strategy based on your use case:

Fetching by Label (Production Use)

Recommended for: Production applications, environment-based deployments, tenant-specific promptsWhy use labels: Your application code remains constant while prompt content can be updated by reassigning labels. Enables non-technical team members to deploy prompt changes.Python SDK:

from abvdev import ABV

abv = ABV(api_key="sk-abv-...", host="https://app.abv.dev")

# Fetch production version (default)
prompt = abv.get_prompt("movie-critic")

# Fetch staging version
staging_prompt = abv.get_prompt("movie-critic", label="staging")

# Fetch latest version (most recently created)
latest_prompt = abv.get_prompt("movie-critic", label="latest")

# Fetch tenant-specific version
tenant_prompt = abv.get_prompt("movie-critic", label="tenant-acme")

JavaScript/TypeScript SDK:

import { ABVClient } from "@abvdev/client";
const abv = new ABVClient();

async function main() {
  // Fetch production version (default)
  const prompt = await abv.prompt.get("movie-critic");

  // Fetch staging version
  const stagingPrompt = await abv.prompt.get("movie-critic", {
    label: "staging",
  });

  // Fetch latest version
  const latestPrompt = await abv.prompt.get("movie-critic", {
    label: "latest",
  });
}

main();

Default behavior: When no label is specified, ABV returns the version with the production label.latest label: Automatically maintained by ABV, always points to the most recently created version.

Fetching by Version (Debugging and Testing)

Recommended for: Debugging specific versions, comparing prompt performance, reproducing issuesWhy use versions: Absolute version numbers don’t change. Version 1 is always version 1, useful for debugging and reproducibility.Python SDK:

from abvdev import ABV

abv = ABV(api_key="sk-abv-...", host="https://app.abv.dev")

# Fetch specific version
v1 = abv.get_prompt("movie-critic", version=1)
v2 = abv.get_prompt("movie-critic", version=2)
v3 = abv.get_prompt("movie-critic", version=3)

# Compare versions
print(f"Version 1: {v1.prompt}")
print(f"Version 2: {v2.prompt}")

JavaScript/TypeScript SDK:

import { ABVClient } from "@abvdev/client";
const abv = new ABVClient();

async function main() {
  // Fetch specific versions
  const v1 = await abv.prompt.get("movie-critic", { version: 1 });
  const v2 = await abv.prompt.get("movie-critic", { version: 2 });
  const v3 = await abv.prompt.get("movie-critic", { version: 3 });

  // Compare versions
  console.log(`Version 1: ${v1.prompt}`);
  console.log(`Version 2: ${v2.prompt}`);
}

main();

Use cases:

Debugging: “Which version was in production when the issue occurred?”
Comparison: “What changed between version 2 and version 3?”
Reproducibility: “Re-run evaluation on version 1 to compare with version 5”

Deployment Workflows

Common workflows using versions and labels:

Standard Deployment Workflow

Scenario: Deploy a new prompt version safely through staging before production.Steps:

Develop: Create new prompt version in ABV UI or via SDK
- Version 4 is created
- Automatically gets latest label
Stage: Assign staging label to version 4
- Test in staging environment that fetches label="staging"
- Review linked traces and metrics in ABV dashboard
Validate: Confirm version 4 performs well in staging
- Check quality scores, latency, costs
- Review sample responses
Deploy: Reassign production label from version 3 to version 4
- Production traffic immediately uses version 4
- No code changes, CI/CD, or application restarts
Monitor: Watch metrics for version 4 in production
- Track quality scores, user feedback, error rates
- Compare performance with version 3
Rollback (if needed): Reassign production back to version 3
- Instant revert if issues arise

Timeline: Minutes from creation to production deployment, seconds to rollback.

A/B Testing Workflow

Scenario: Compare two prompt variants in production to identify the better performer.Steps:

Create variants:
- Version 2: Variant A content, assign variant-a label
- Version 3: Variant B content, assign variant-b label

Implement randomization in application code:

import random
variant = random.choice(["variant-a", "variant-b"])
prompt = abv.get_prompt("movie-critic", label=variant)

Link prompts to traces: Track which variant generated each response
```
abv.update_current_generation(prompt=prompt)
```
Collect data: Run A/B test for sufficient sample size (days to weeks)
Analyze metrics: Compare quality scores, latency, user feedback by prompt version
- Use ABV’s metrics dashboard filtered by prompt version
- Calculate statistical significance
Promote winner: Reassign production label to the better-performing variant

Learn more about A/B testing →

Multi-Environment Workflow

Scenario: Manage separate prompt versions for development, staging, and production environments.Setup:

Version 1: Stable production version, labels: ["production", "stable"]
Version 2: Current staging version, labels: ["staging"]
Version 3: Development version, labels: ["development", "latest"]

Application code (environment-aware):

import os

env = os.getenv("ENVIRONMENT", "production")  # development, staging, or production
prompt = abv.get_prompt("movie-critic", label=env)

Promotion workflow:

Develop in development environment using version 3
Promote to staging: Reassign staging label to version 3
Test in staging environment
Promote to production: Reassign production label to version 3
Version 3 now deployed across all environments

Benefits: Clear separation between environments, gradual rollout, isolated testing.

Tenant-Specific Workflow

Scenario: Different customers (tenants) need customized prompts with their specific requirements.Setup:

Version 1: Generic prompt, labels: ["production", "default"]
Version 2: ACME Corp customization, labels: ["tenant-acme"]
Version 3: Contoso customization, labels: ["tenant-contoso"]

Application code (tenant-aware):

def get_tenant_prompt(tenant_id):
    tenant_label = f"tenant-{tenant_id}"
    try:
        return abv.get_prompt("support-greeting", label=tenant_label)
    except:
        # Fallback to default if tenant-specific prompt doesn't exist
        return abv.get_prompt("support-greeting", label="default")

# Fetch based on current tenant context
tenant = get_current_tenant()
prompt = get_tenant_prompt(tenant.id)

Benefits: Customized experience per customer, no separate codebases, centralized management.

Emergency Rollback Workflow

Scenario: A newly deployed prompt version causes production issues. You need to roll back immediately.Steps:

Detect issue: Monitoring alerts show increased error rate or degraded quality after prompt deployment
Identify previous version: Check prompt history to see what version had the production label before
Rollback in ABV UI:
- Navigate to prompt in dashboard
- Remove production label from current version (version 4)
- Assign production label to previous version (version 3)
Verify rollback: Check monitoring to confirm issues are resolved
Post-mortem: Compare version 3 and version 4 in ABV UI to identify what caused the issue
Fix and redeploy: Create version 5 with fix, test in staging, then promote to production

Rollback time: Under 30 seconds from decision to revert.No code deployment required: Instant rollback without CI/CD pipelines or application restarts.

Version Comparison and Diffs

ABV provides tools for understanding how prompts evolve:

Prompt Diff View

The ABV UI shows side-by-side diffs between prompt versions, highlighting exactly what changed.What’s shown:

Prompt content changes: Text additions, deletions, and modifications
Config changes: Model parameter updates, tool definition changes
Label changes: Which labels were added or removed
Metadata: Creation timestamps, creators, commit messages

Use cases:

Debugging: “What changed between the working version and the broken version?”
Review: “What did this commit message refer to?”
Audit: “Who changed the production prompt and when?”
Learning: “How has this prompt evolved over the past month?”

Access: Navigate to any prompt in the ABV dashboard and select “Compare Versions” to view diffs.

Version History and Metadata

Each version stores comprehensive metadata for audit trails and debugging:Stored metadata:

Version number: Incremental integer (1, 2, 3…)
Creation timestamp: Exact time version was created
Creator: User or API key that created the version
Commit message: Optional description of what changed
Labels: Current labels pointing to this version
Content snapshot: Complete prompt content and config

Immutability: Version metadata and content never change after creation, ensuring:

Reproducibility: Fetching version 1 always returns identical data
Audit compliance: Complete, tamper-proof history
Debugging accuracy: Historical context for issue investigation

Retention: Versions are retained indefinitely unless explicitly deleted by admins.

Protected Prompt Labels

Prevent accidental changes to critical labels with label protection:

How Protected Labels Work

Protected labels can only be modified by admins and owners, preventing members and viewers from accidentally changing production prompts.Default protected label: production (recommended)Custom protected labels: Protect any label (stable, prod-a, tenant labels) based on your workflowPermission matrix:

Role	Can modify protected labels?
Owner	✅ Yes
Admin	✅ Yes
Member	❌ No
Viewer	❌ No

Blocked actions for members/viewers:

Cannot add protected label to a version
Cannot remove protected label from a version
Cannot delete a prompt with a protected label
Cannot delete a version with a protected label

Allowed actions for members/viewers:

Create new prompt versions (without protected labels)
Assign non-protected labels (staging, development)
View all versions and their labels

Learn more about RBAC →

Configuring Protected Labels

Admins and owners configure label protection in project settings.Steps:

Navigate to Project Settings in ABV dashboard
Select Prompt Management settings
View list of labels used in the project
Toggle protection status for each label
Save changes

Recommendation: Protect the production label to prevent accidental production deployments by non-admin users.Use cases:

Compliance: Ensure only admins can change production prompts for audit requirements
Safety: Prevent junior team members from accidentally deploying untested prompts
Governance: Implement approval workflows where only leads promote to production

Protected Label Workflows

Scenario: Team with mixed permissions where members can create and test prompts, but only admins deploy to production.Setup:

Admin configures production label as protected
Members have permission to create prompts and assign non-protected labels

Workflow:

Member creates prompt: Version 4 created, assigns staging label
Member tests: Tests in staging environment, validates quality
Member requests promotion: Notifies admin that version 4 is ready
Admin reviews: Reviews metrics, compares versions, validates readiness
Admin promotes: Reassigns production label from version 3 to version 4
Deployment complete: Production uses version 4

Benefits:

Members can iterate rapidly without admin involvement
Admins control what reaches production
Audit trail shows who deployed what and when
Prevents accidental production changes

Next Steps

Get Started

Create your first versioned prompt and integrate with your application

Prompts Data Model

Deep dive into prompt structure, fields, and versioning concepts

A/B Testing

Compare prompt versions in production with A/B testing workflows

Link Prompts to Traces

Track metrics by prompt version through observability integration

Protected Labels (RBAC)

Configure permissions and label protection for governance

Caching

Understand how client-side caching enables zero-latency prompt fetching

Documentation Index

​How Version Control Works

​Assigning and Managing Labels

​Fetching Prompts by Label or Version

​Deployment Workflows

​Version Comparison and Diffs

​Protected Prompt Labels

​Next Steps