Managing Prompt Versions

This guide walks through the canonical loop for evolving a production prompt: edit on development, diff, promote, monitor, and revert if a regression sneaks through. It assumes you already understand the prompts data model.

1. 1

   Save a new version on development

   Open the prompt and click Edit. Make your change — body, model, temperature, anything. Save. PromptHelm bumps the minor version (e.g. 1.4.0 → 1.5.0) and lands the new snapshot on the development branch. production is untouched.

2. 2

   Diff against current production

   The version list shows every snapshot with a Compare action. Pick the new version on the left, the current production version on the right. The diff highlights changes to the body, system prompt, variable schema, and parameter overrides.

   Read the parameter diff carefully

   A temperature swing from 0.2 to 0.8 is invisible in the body diff but can wreck reproducibility. Use the parameter pane.

3. 3

   Promote to production

   Click Promote. PromptHelm flips the production pointer atomically and writes a prompt.promote entry to the audit log. Live SDK and gateway calls hitting production now resolve to the new version.

   curl -X POST https://api.prompthelm.app/api/v1/prompts/$ID/versions/$VERSION_ID/promote \
     -H "Authorization: Bearer $PROMPTHELM_API_KEY"

4. 4

   Monitor analytics

   Open the Analytics tab. Compare the p95 latency, success rate, and average cost between the new version and the previous one across a few hundred calls. A regression usually shows up within minutes of real traffic.

5. 5

   Revert if needed

   If anything looks wrong, find the previous production version in the list and click Revert. The pointer swings back; no version is deleted. You then have a clean diff to root-cause the bad version without a stop-the-world incident.

Next steps