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

# Prompt Version Control

> Manage prompt versions, labels, and deployments with safe rollbacks and environment-based releases

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:

<Steps>
  <Step title="Automatic version creation" icon="plus">
    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.
  </Step>

  <Step title="Label assignment and management" icon="tag">
    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
  </Step>

  <Step title="Fetching prompts by label or version" icon="download">
    Your application fetches prompts using labels (for deployment management) or version numbers (for debugging or specific version testing).

    **Fetching by label** (recommended for production):

    ```python theme={null}
    # 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):

    ```python theme={null}
    # 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.
  </Step>

  <Step title="Deployment via label reassignment" icon="rocket">
    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.
  </Step>

  <Step title="Rollback to previous versions" icon="rotate-left">
    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.
  </Step>
</Steps>

# Assigning and Managing Labels

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

<AccordionGroup>
  <Accordion title="Via ABV UI (Recommended for Deployment)" icon="browser">
    The ABV UI provides visual label management for non-technical team members.

    **Steps**:

    1. Navigate to **Prompts** in the ABV dashboard
    2. Select the prompt you want to manage
    3. View all versions in the version history panel
    4. For each version, see current labels and add/remove labels via dropdown
    5. 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.
  </Accordion>

  <Accordion title="Python SDK" icon="python">
    Assign labels when creating prompts or update labels on existing versions.

    **Assign labels when creating**:

    ```python theme={null}
    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**:

    ```python theme={null}
    # 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.
  </Accordion>

  <Accordion title="JavaScript/TypeScript SDK" icon="js">
    Assign labels when creating prompts or update labels on existing versions.

    **Environment setup**:

    ```bash theme={null}
    npm install @abvdev/client dotenv
    ```

    ```bash title=".env" theme={null}
    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**:

    ```typescript theme={null}
    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**:

    ```typescript theme={null}
    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.
  </Accordion>
</AccordionGroup>

# Fetching Prompts by Label or Version

Choose the appropriate fetching strategy based on your use case:

<AccordionGroup>
  <Accordion title="Fetching by Label (Production Use)" icon="tag">
    **Recommended for**: Production applications, environment-based deployments, tenant-specific prompts

    **Why 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**:

    ```python theme={null}
    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**:

    ```typescript theme={null}
    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.
  </Accordion>

  <Accordion title="Fetching by Version (Debugging and Testing)" icon="hashtag">
    **Recommended for**: Debugging specific versions, comparing prompt performance, reproducing issues

    **Why use versions**: Absolute version numbers don't change. Version 1 is always version 1, useful for debugging and reproducibility.

    **Python SDK**:

    ```python theme={null}
    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**:

    ```typescript theme={null}
    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"
  </Accordion>
</AccordionGroup>

# Deployment Workflows

Common workflows using versions and labels:

<AccordionGroup>
  <Accordion title="Standard Deployment Workflow" icon="rocket">
    **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.
  </Accordion>

  <Accordion title="A/B Testing Workflow" icon="flask">
    **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:
       ```python theme={null}
       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
       ```python theme={null}
       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 →](/developer/prompt-management/ab-testing-llm-prompts)
  </Accordion>

  <Accordion title="Multi-Environment Workflow" icon="layer-group">
    **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):

    ```python theme={null}
    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.
  </Accordion>

  <Accordion title="Tenant-Specific Workflow" icon="users">
    **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):

    ```python theme={null}
    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.
  </Accordion>

  <Accordion title="Emergency Rollback Workflow" icon="rotate-left">
    **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.
  </Accordion>
</AccordionGroup>

# Version Comparison and Diffs

ABV provides tools for understanding how prompts evolve:

<AccordionGroup>
  <Accordion title="Prompt Diff View" icon="code-compare">
    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.
  </Accordion>

  <Accordion title="Version History and Metadata" icon="clock">
    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.
  </Accordion>
</AccordionGroup>

# Protected Prompt Labels

Prevent accidental changes to critical labels with label protection:

<AccordionGroup>
  <Accordion title="How Protected Labels Work" icon="lock">
    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 workflow

    **Permission 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 →](/developer/platform/administration/role-based-access-controls)
  </Accordion>

  <Accordion title="Configuring Protected Labels" icon="gear">
    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
  </Accordion>

  <Accordion title="Protected Label Workflows" icon="workflow">
    **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
  </Accordion>
</AccordionGroup>

# Next Steps

<CardGroup cols={2}>
  <Card title="Get Started" icon="rocket" href="/developer/prompt-management/get-started">
    Create your first versioned prompt and integrate with your application
  </Card>

  <Card title="Prompts Data Model" icon="database" href="/developer/prompt-management/prompts-data-model">
    Deep dive into prompt structure, fields, and versioning concepts
  </Card>

  <Card title="A/B Testing" icon="flask" href="/developer/prompt-management/ab-testing-llm-prompts">
    Compare prompt versions in production with A/B testing workflows
  </Card>

  <Card title="Link Prompts to Traces" icon="link" href="/developer/prompt-management/link-prompts-to-traces">
    Track metrics by prompt version through observability integration
  </Card>

  <Card title="Protected Labels (RBAC)" icon="shield" href="/developer/platform/administration/role-based-access-controls">
    Configure permissions and label protection for governance
  </Card>

  <Card title="Caching" icon="bolt" href="/developer/prompt-management/caching-prompts">
    Understand how client-side caching enables zero-latency prompt fetching
  </Card>
</CardGroup>