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 that links all versions together
  • currentVersion indicates the active version number
  • Creating a new version increments the version number automatically
  • Previous versions are preserved indefinitely for comparison and rollback
  • Version history includes timestamps and metadata for auditing

​
Create New Version

When you update a prompt’s content, create a new version to preserve history: 
// Create a new version with updated content
const newVersion = await client.prompts.createVersion('prompt_xxxx', {
  content: `You are an expert support agent for {{company_name}}.

Customer question: {{customer_question}}

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

Be helpful, professional, and concise.`,
});

console.log('New version:', newVersion.currentVersion); // 2, 3, etc.

​
Version History

Retrieve the complete history of a prompt to see all changes over time: 
// List all versions of a prompt
const versions = await client.prompts.listVersions('prompt_group_xxxx');

versions.data.forEach(v => {
  console.log(`v${v.currentVersion}:`);
  console.log(`  Created: ${v.createdAt}`);
  console.log(`  Status: ${v.status}`);
  console.log(`  Content preview: ${v.content.substring(0, 50)}...`);
});

​
Compare Versions

​
Via Dashboard

  1. Open a prompt in the MutagenT dashboard
  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.prompts.getVersion('prompt_group_xxxx', 1);
const v2 = await client.prompts.getVersion('prompt_group_xxxx', 2);

console.log('Version 1 content:', v1.content);
console.log('Version 2 content:', v2.content);

// Compare evaluation scores if both have been evaluated
if (v1.evaluationScore && v2.evaluationScore) {
  const improvement = v2.evaluationScore - v1.evaluationScore;
  console.log(`Score change: ${improvement > 0 ? '+' : ''}${improvement.toFixed(2)}`);
}

​
Rollback to Previous Version

If a new version causes issues, rollback to a known working version: 
// Rollback to version 2
const rolledBack = await client.prompts.rollback('prompt_group_xxxx', {
  targetVersion: 2,
});

console.log('Rolled back to version:', rolledBack.currentVersion);
Rollback creates a new version with the content from the target version. The version number continues to increment (e.g., rolling back from v5 to v2 creates v6 with v2’s content).

​
Best Practices

Create versions for meaningful changes that affect behavior:
  • Changes to instructions or tone
  • Adding/removing sections
  • Structural reorganization
Don’t create versions for:
  • Typo fixes (update in place)
  • Whitespace changes
Run evaluations on new versions before setting as active:
// 1. Create new version
const newVersion = await client.prompts.createVersion(promptId, { content: '...' });

// 2. Run evaluation
const evaluation = await client.evaluations.run({
  promptId: newVersion.id,
  datasetId: 'dataset_xxxx',
  metrics: ['g_eval'],
});

// 3. Check results before publishing
const results = await client.evaluations.getResults(evaluation.id);
if (results.overallScore >= 0.85) {
  await client.prompts.publish(newVersion.id);
}
Use descriptions to note what changed and why:
await client.prompts.createVersion(promptId, {
  content: 'Updated content...',
  description: 'Added structured output format for better parsing',
});
Set minimum scores that new versions must meet:
  • Prevents regressions from being deployed
  • Automated quality assurance
  • Tracks improvement over time

​
Version States

StateDescriptionCan Deploy?
draftWork in progressNo
testedPassed evaluationYes
publishedActive in productionYes (current)
archivedNo longer in useNo