Skip to main content
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:
  1. Create new prompt version (version 4)
  2. Assign staging label to version 4 for testing
  3. Test in staging environment (fetches staging label)
  4. After validation, reassign production label from version 3 to version 4 in ABV UI
  5. 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:
  1. Notice issues with version 4 in production
  2. Open ABV UI, navigate to prompt
  3. Reassign production label from version 4 back to version 3
  4. 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:
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.
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:
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.
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:
Scenario: Deploy a new prompt version safely through staging before production.Steps:
  1. Develop: Create new prompt version in ABV UI or via SDK
    • Version 4 is created
    • Automatically gets latest label
  2. Stage: Assign staging label to version 4
    • Test in staging environment that fetches label="staging"
    • Review linked traces and metrics in ABV dashboard
  3. Validate: Confirm version 4 performs well in staging
    • Check quality scores, latency, costs
    • Review sample responses
  4. Deploy: Reassign production label from version 3 to version 4
    • Production traffic immediately uses version 4
    • No code changes, CI/CD, or application restarts
  5. Monitor: Watch metrics for version 4 in production
    • Track quality scores, user feedback, error rates
    • Compare performance with version 3
  6. Rollback (if needed): Reassign production back to version 3
    • Instant revert if issues arise
Timeline: Minutes from creation to production deployment, seconds to rollback.
Scenario: Compare two prompt variants in production to identify the better performer.Steps:
  1. Create variants:
    • Version 2: Variant A content, assign variant-a label
    • Version 3: Variant B content, assign variant-b label
  2. Implement randomization in application code: 
    import random
variant = random.choice(["variant-a", "variant-b"])
prompt = abv.get_prompt("movie-critic", label=variant)
  3. Link prompts to traces: Track which variant generated each response 
    abv.update_current_generation(prompt=prompt)
  4. Collect data: Run A/B test for sufficient sample size (days to weeks)
  5. Analyze metrics: Compare quality scores, latency, user feedback by prompt version
    • Use ABV’s metrics dashboard filtered by prompt version
    • Calculate statistical significance
  6. Promote winner: Reassign production label to the better-performing variant
Learn more about A/B testing →
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:
  1. Develop in development environment using version 3
  2. Promote to staging: Reassign staging label to version 3
  3. Test in staging environment
  4. Promote to production: Reassign production label to version 3
  5. Version 3 now deployed across all environments
Benefits: Clear separation between environments, gradual rollout, isolated testing.
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.
Scenario: A newly deployed prompt version causes production issues. You need to roll back immediately.Steps:
  1. Detect issue: Monitoring alerts show increased error rate or degraded quality after prompt deployment
  2. Identify previous version: Check prompt history to see what version had the production label before
  3. 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)
  4. Verify rollback: Check monitoring to confirm issues are resolved
  5. Post-mortem: Compare version 3 and version 4 in ABV UI to identify what caused the issue
  6. 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:
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.
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:
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:
RoleCan 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 →
Admins and owners configure label protection in project settings.Steps:
  1. Navigate to Project Settings in ABV dashboard
  2. Select Prompt Management settings
  3. View list of labels used in the project
  4. Toggle protection status for each label
  5. 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
Scenario: Team with mixed permissions where members can create and test prompts, but only admins deploy to production.Setup:
  1. Admin configures production label as protected
  2. Members have permission to create prompts and assign non-protected labels
Workflow:
  1. Member creates prompt: Version 4 created, assigns staging label
  2. Member tests: Tests in staging environment, validates quality
  3. Member requests promotion: Notifies admin that version 4 is ready
  4. Admin reviews: Reviews metrics, compares versions, validates readiness
  5. Admin promotes: Reassigns production label from version 3 to version 4
  6. 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