Skip to main content

​
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

  • 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
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.

​
Create New Version

When you update a prompt’s content, create a new version to preserve history: 
// Create a new version from an existing prompt
const newVersion = await client.prompt.createPromptVersion({
  id: 123,                          // Base prompt ID
  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"

​
Version History

Retrieve prompts filtered by version or latest flag: 
// 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',
});

​
Compare Versions

​
Via Dashboard

  1. Open a prompt in the MutagenT dashboard at 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

// 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

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
mutagent prompts create --name "prompt-v2" --system "Updated system prompt" --human "{input}" --output-schema '{"type":"object","properties":{"result":{"type":"string"}}}'
Run evaluations on new versions before setting as active:
# 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>
Use descriptions and metadata to note what changed and why:
{
  "name": "Customer Support",
  "version": "1.1.0",
  "description": "Added structured output format for better parsing",
  "metadata": {
    "changelog": "Improved tone, added response structure"
  }
}
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

​
Version Lifecycle