Prompt Versioning

Track changes, create versions, and manage your prompt evolution

Version Structure

Helicone uses semantic versioning for prompts with major and minor versions:

• Major versions (1.0, 2.0, 3.0) - Significant changes or breaking updates
• Minor versions (1.1, 1.2, 1.3) - Incremental improvements within a major version

Prompt: customer-support-agent
├── v1.0 - Initial version
├── v1.1 - Added more context
├── v1.2 - Refined tone
├── v2.0 - Complete rewrite with new structure
└── v2.1 - Bug fix for edge cases

Creating Versions

Via API

Create a new version with a commit message:

import { getJawnClient } from "./lib/clients/jawn";

const jawn = getJawnClient(orgId);

const response = await jawn.POST("/v1/prompt-2025/update", {
  body: {
    promptId: "your-prompt-id",
    promptVersionId: "current-version-id",
    newMajorVersion: false, // true for major, false for minor
    commitMessage: "Improved system instructions for better accuracy",
    promptBody: {
      model: "gpt-4",
      messages: [
        {
          role: "system",
          content: "You are a helpful assistant specialized in {{hc:domain:string}}.",
        },
        {
          role: "user",
          content: "{{hc:user_query:string}}",
        },
      ],
      temperature: 0.7,
      max_tokens: 1000,
    },
  },
});

Version Metadata

Each version includes:

interface Prompt2025Version {
  id: string;                  // Unique version ID
  model: string;               // LLM model (e.g., "gpt-4")
  prompt_id: string;           // Parent prompt ID
  major_version: number;       // Major version number
  minor_version: number;       // Minor version number
  commit_message: string;      // Description of changes
  environments?: string[];     // Deployed environments
  created_at: string;          // ISO timestamp
  s3_url?: string;            // S3 location of prompt body
}

Querying Versions

Get All Versions

const response = await jawn.POST("/v1/prompt-2025/query/versions", {
  body: {
    promptId: "your-prompt-id",
  },
});

const versions = response.data?.data || [];
versions.forEach((version) => {
  console.log(`v${version.major_version}.${version.minor_version}: ${version.commit_message}`);
});

Get Specific Version

const response = await jawn.POST("/v1/prompt-2025/query/version", {
  body: {
    promptVersionId: "version-id",
  },
});

const version = response.data?.data;

Get Production Version

const response = await jawn.POST("/v1/prompt-2025/query/production-version", {
  body: {
    promptId: "your-prompt-id",
  },
});

const productionVersion = response.data?.data;

Comparing Versions

The Helicone UI allows you to compare versions side-by-side:

1. Navigate to your prompt in the dashboard
2. Select two versions to compare
3. View diff highlighting changes in:
   • Messages and content
   • Model parameters (temperature, max_tokens, etc.)
   • Tools and function definitions
   • Variables and their types

Version Counts

const response = await jawn.POST("/v1/prompt-2025/query/total-versions", {
  body: {
    promptId: "your-prompt-id",
  },
});

const counts = response.data?.data;
// { totalVersions: 15, majorVersions: 3 }

Retrieving Version Body

Get the full prompt body for a specific version:

const response = await jawn.GET("/v1/prompt-2025/{promptVersionId}/prompt-body", {
  params: {
    path: {
      promptVersionId: "version-id",
    },
  },
});

const promptBody = response.data?.data;
// Returns the complete prompt with messages, tools, parameters

Rollback Strategy

To rollback to a previous version:

1. Identify the Target Version

const versions = await jawn.POST("/v1/prompt-2025/query/versions", {
  body: { promptId: "your-prompt-id" },
});

const targetVersion = versions.data?.data?.find(
  (v) => v.major_version === 1 && v.minor_version === 5
);

2. Deploy to Production

await jawn.POST("/v1/prompt-2025/update/environment", {
  body: {
    promptId: "your-prompt-id",
    promptVersionId: targetVersion.id,
    environment: "production",
  },
});

3. Verify the Change

const prodVersion = await jawn.POST("/v1/prompt-2025/query/environment-version", {
  body: {
    promptId: "your-prompt-id",
    environment: "production",
  },
});

console.log(`Rolled back to v${prodVersion.data?.data?.major_version}.${prodVersion.data?.data?.minor_version}`);

Best Practices

Commit Messages

Write clear, descriptive commit messages:

• Good: “Improved system instructions to reduce hallucinations in medical queries”
• Bad: “Updated prompt”

Major vs Minor Versions

Use major versions for:

• Complete prompt rewrites
• Changing the model (e.g., GPT-3.5 → GPT-4)
• Breaking changes to variables or structure
• New tool/function definitions

Use minor versions for:

• Refining wording or instructions
• Adjusting temperature or max_tokens
• Adding examples or context
• Bug fixes

Version Testing

Always test new versions before deploying to production:

1. Create a new version
2. Deploy to development environment
3. Run integration tests
4. Deploy to staging for QA
5. Monitor metrics and quality
6. Deploy to production when validated

Audit Trail

Version history provides an audit trail:

• Track who created each version
• Understand why changes were made
• Correlate prompt changes with performance metrics
• Debug issues by comparing current vs previous versions

Next Steps

Deployment

Learn how to deploy versions to environments

SDK Integration

Use versions in your application code