Prompts as Versioned Code
How PromptHelm treats prompts: branches, immutable versions, and production deployment.
PromptHelm treats prompts as code, not strings. Every prompt is a first-class aggregate with its own identity, configuration, version history, and deployment branches — managed with the same rigor you would apply to a database schema or an API contract.
The prompt aggregate
A single prompt bundles everything required to reproduce a call:
| Name | Type | Default | Description |
|---|---|---|---|
| name* | string | — | Human-readable label shown across the dashboard. |
| slug* | string | — | URL-safe identifier used by the SDK and gateway. |
| model* | string | — | Default model (e.g. gpt-5, claude-sonnet-4-5). |
| temperature | number | — | Sampling temperature (0.0 – 2.0). |
| maxTokens | number | — | Hard ceiling on output tokens. |
| topP | number | — | Nucleus sampling threshold. |
| stopSequences | string[] | — | Substrings that terminate generation early. |
| content* | { system, user, variables } | — | Prompt body and declared {{variable}} schema. |
Versions are immutable
Every save bumps a semantic version (1.0.0, 1.1.0, 2.0.0).
Versions are write-once snapshots — once created, the content, model,
and parameters are frozen. This is what lets analytics, audit, and
rollback operate on a stable identity.
Versioning is automatic
Every save bumps the minor version. Major bumps are reserved for breaking changes to the variable schema.
Branches: production and development
Each prompt exposes two long-lived branches:
production— the version your live traffic hits.development— the staging surface for new versions.
A new save lands on development by default. You promote it to
production only when you are ready.
Promotion and rollback
Promotion is explicit. From the dashboard, click Promote on any version, or call:
curl -X POST https://api.prompthelm.app/api/v1/prompts/:promptId/versions/:versionId/promote \
-H "Authorization: Bearer $PROMPTHELM_API_KEY"Rollback is the same operation pointed at an older version. The previous production version remains intact in the version list — no history is ever lost.
Diff view and the playground
Before promoting, the dashboard shows a side-by-side diff between the candidate and the current production version (content, model, parameters). Pair it with the Playground to test the new version against representative inputs.
Variable interpolation
Use {{ variable_name }} in the prompt body. Variables become a typed
schema enforced at execute time:
await client.execute({
promptSlug: "support-triage",
variables: { ticket: "Password reset email never arrived." },
});