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

# Prompt Versioning

> Version control for your prompts

# Prompt Versioning

Every prompt in MutagenT has full version history, allowing you to track changes, compare versions, and rollback when needed. Version control ensures you never lose a working prompt and can always trace how your prompts evolved.

## How Versioning Works

<Mermaid>
  flowchart TD
  subgraph PromptGroup\["promptGroupId (links all versions)"]
  V1\["v1.0.0<br />Draft"] --> V2\["v1.1.0<br />Tested"] --> V3\["v2.0.0<br />Optimized"] --> V4\["v2.1.0<br />Published"]
  end

  style V1 fill:#64748B,color:#fff
  style V2 fill:#06B6D4,color:#000
  style V3 fill:#7C3AED,color:#fff
  style V4 fill:#10B981,color:#000
</Mermaid>

* Each prompt has a `promptGroupId` (UUID) that links all versions together
* Versions use **semantic versioning** (e.g., `1.0.0`, `1.1.0`, `2.0.0`)
* The `isLatest` flag marks which version is the active version
* On first creation, `isLatest` is automatically set to `true` if no other version with the same name exists
* When updating a prompt, the version number is automatically incremented
* Previous versions are preserved indefinitely for comparison and rollback

<Note>
  The `isLatest` flag is automatically managed. When you create the first version of a prompt, it is marked as latest. When you create a new version and mark it as latest, the previous latest version is automatically unflagged.
</Note>

## Create New Version

When you update a prompt's content, create a new version to preserve history:

<CodeGroup>
  ```typescript SDK theme={null}
  // Create a new version from an existing prompt
  const newVersion = await client.prompt.createPromptVersion({
    id: 123,                          // Base prompt ID
    body: {
      newVersion: '1.1.0',           // New semantic version
      changes: {
        systemPrompt: `You are an expert support agent for {company_name}.

  Respond with:
  1. A direct answer
  2. Any relevant follow-up information
  3. Links to documentation if applicable

  Be helpful, professional, and concise.`,
        isLatest: true,              // Mark this as the active version
      },
    },
  });

  console.log('New version:', newVersion.version); // "1.1.0"
  ```

  ```bash CLI theme={null}
  # Update a prompt (automatically creates a new version)
  mutagent prompts update <prompt-id> \
    --system "Updated system prompt with improved instructions"

  # Update with raw prompt text
  mutagent prompts update <prompt-id> --raw "Updated prompt text"
  ```

  ```bash cURL theme={null}
  # Create a new version via the versioning endpoint
  curl -X POST https://api.mutagent.io/api/prompt/123/versions \
    -H "x-api-key: mt_xxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "newVersion": "1.1.0",
      "changes": {
        "systemPrompt": "Updated prompt content...",
        "isLatest": true
      }
    }'
  ```
</CodeGroup>

## Version History

Retrieve prompts filtered by version or latest flag:

<CodeGroup>
  ```typescript SDK theme={null}
  // List all prompts, filtered to latest versions only
  const latest = await client.prompt.listPrompts({
    isLatest: true,
  });

  latest.result.data.forEach(p => {
    console.log(`${p.name} v${p.version} (latest: ${p.isLatest})`);
  });

  // List all versions of a specific prompt by name
  const allVersions = await client.prompt.listPrompts({
    name: 'Customer Support',
  });
  ```

  ```bash CLI theme={null}
  # List all prompts (shows version column)
  mutagent prompts list

  # Get full prompt details including version info
  mutagent prompts get <prompt-id>

  # Machine-readable output
  mutagent prompts get <prompt-id> --json
  ```
</CodeGroup>

## Compare Versions

### Via Dashboard

1. Open a prompt in the MutagenT dashboard at [app.mutagent.io](https://app.mutagent.io)
2. Click **Version History** in the sidebar
3. Select two versions to compare
4. View side-by-side diff of changes
5. See evaluation scores for each version (if available)

### Via SDK

```typescript theme={null}
// Get two specific versions for comparison
const v1 = await client.prompt.getPrompt({ id: promptV1Id });
const v2 = await client.prompt.getPrompt({ id: promptV2Id });

console.log('Version 1:', v1.version, v1.rawPrompt?.substring(0, 50));
console.log('Version 2:', v2.version, v2.rawPrompt?.substring(0, 50));
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use semantic versioning">
    Follow semantic versioning conventions:

    * **Patch** (`1.0.1`): Minor wording fixes, typo corrections
    * **Minor** (`1.1.0`): Added instructions, new variable support
    * **Major** (`2.0.0`): Structural changes, different output format

    ```bash theme={null}
    mutagent prompts create --name "prompt-v2" --system "Updated system prompt" --human "{input}" --output-schema '{"type":"object","properties":{"result":{"type":"string"}}}'
    ```
  </Accordion>

  <Accordion title="Test before deploying">
    Run evaluations on new versions before setting as active:

    ```bash theme={null}
    # 1. Create new version (do not set as latest yet)
    mutagent prompts update <prompt-id> --raw "Updated prompt..."

    # 2. Run evaluation against a dataset
    mutagent prompts optimize start <prompt-id> --dataset <dataset-id>

    # 3. Check results and promote if quality meets threshold
    mutagent prompts optimize results <job-id>
    ```
  </Accordion>

  <Accordion title="Document changes">
    Use descriptions and metadata to note what changed and why:

    ```json theme={null}
    {
      "name": "Customer Support",
      "version": "1.1.0",
      "description": "Added structured output format for better parsing",
      "metadata": {
        "changelog": "Improved tone, added response structure"
      }
    }
    ```
  </Accordion>

  <Accordion title="Use isLatest for deployment control">
    The `isLatest` flag controls which version is active:

    * Only one version per prompt name can be `isLatest: true`
    * Setting a new version as latest automatically unflags the previous one
    * Use this to implement blue-green deployments for prompts
  </Accordion>
</AccordionGroup>

## Version Lifecycle

<Mermaid>
  flowchart TD
  A\["Create v1.0.0<br />isLatest: true"] --> B{"Update prompt"}
  B --> C\["Create v1.1.0<br />isLatest: true"]
  C --> D\["v1.0.0 auto-unflagged<br />isLatest: false"]
  C --> E{"Evaluate v1.1.0"}
  E -- "Score OK" --> F\["Keep v1.1.0 as latest"]
  E -- "Regression" --> G\["Create v1.1.1 with v1.0.0 content<br />isLatest: true"]

  style A fill:#64748B,color:#fff
  style C fill:#06B6D4,color:#000
  style F fill:#10B981,color:#000
  style G fill:#F59E0B,color:#000
</Mermaid>