Or hand it to your coding agent
Paste this into Claude Code, Cursor or any agent that edits your repository.
Move this app's hard-coded LLM prompts to PromptHelm…
- 1
Create an account
Sign up with your email; we send you a link, so there's no password. Then create a project. One project per app keeps its keys and prompts apart.
Start for free - 2
Add your prompt
Choose New prompt, give it a slug and paste the prompt your app sends today. The slug is the name your code asks for: lowercase letters, digits and hyphens, like
support-reply. Mark each part that changes per request as a variable in double braces:You are the support assistant for {{company}}. Answer {{customer_name}}'s question in two or three sentences.
Press ⌘↵ (Ctrl ↵ on Windows and Linux) to review the diff and publish.
Not published yet?
Until a prompt is published, the API answers 404 and the SDK serves your fallback. - 3
Create an API key
Open API keys and create a key for this app. It's shown once, so put it in your server's environment straight away:
.envPROMPTHELM_API_KEY=ph_…Keep keys on the server
A key reads the published prompts of its own project. Never ship one in code that runs in a browser or a mobile app. - 4
Install the SDK
$ npm install @prompt-helm/sdkIt runs on Node.js 18 and later, from ESM or CommonJS, with no dependencies.
- 5
Fetch the prompt
Ask for the prompt where your code used to hard-code it:
app.tsimport { PromptHelm } from "@prompt-helm/sdk"; // One client for the whole app: it holds the cache. export const ph = new PromptHelm(); const system = await ph.get("support-reply", { vars: { company: "Acme", customer_name: user.name }, fallback: SUPPORT_REPLY, // the prompt you had hard-coded }); // Pass `system` to your model exactly as you did before.- The first call fetches the prompt. Later calls return it from memory and refresh it in the background once it's older than 60 seconds.
- With a fallback,
getdoesn't throw. A timeout, a network error, a bad key, a missing prompt or a missing variable returns the fallback and callsonError. - Variables are filled in here, on your server. Their values never reach PromptHelm.
- 6
Change it without a deploy
Edit the prompt in the dashboard and publish. Your app serves the new version after its next refresh. To go back, open History and make an older version live; your app follows the same way. The prompt versioning guide explains how versions and rollback work.
That's it. You're live.
From now on a prompt change is an edit and a publish: no pull request, no deploy.
Start for free
Reference
Client options
Pass these to new PromptHelm({ … }). Every one is optional when the environment variables are set.
- apiKey
- Your project's API key.Default
PROMPTHELM_API_KEY - baseUrl
- Where prompts are fetched from.Default
PROMPTHELM_BASE_URL, then https://prompthelm.app - ttl
- How long, in ms, a prompt is served before the SDK checks for a newer version.Default
60000 - timeout
- How long, in ms, one request may take.Default
3000 - onError
- Called with the error and the slug whenever a fallback or a cached prompt was served instead of failing.Default
console.warn - reportFallbacks
- Tells PromptHelm, by error code only, when a fallback or a cached prompt was served, so the prompt's page shows which app fell back and why. Never the text or any variable value.Default
true - reportResults
- During an A/B test, sends PromptHelm totals only: calls served per version, and the outcomes and usage your code reports. Never the text, a variable value or the unit.Default
reportFallbacks - onResolve
- Called on every get and resolve with the slug, the version served and the A/B test, so your own analytics or traces can carry the version.Default
none - fetch
- Your own fetch, for tests or a proxy.Default
global fetch
Errors
Failures are PromptHelmErrors with a code, a message and, for HTTP errors, a status. Without a fallback, get throws them; with one, onError receives them.
- unauthorized
- The API key is missing, wrong or revoked.
- not_found
- This project has no published prompt with that slug.
- missing_variables
- The live version uses a variable your call doesn't pass.
- timeout
- No response within the timeout.
- network
- PromptHelm couldn't be reached.
- server
- Anything else, such as a 5xx response.
Fallbacks that stay current
A fallback is only as good as its text, and a copy kept in your code drifts from what you publish. Write every published prompt to one file instead, and pass it as the fallback:
npx @prompt-helm/sdk pull --out src/prompthelm.fallbacks.tsimport { fallbacks } from "./prompthelm.fallbacks";
const system = await ph.get("support-reply", {
vars: { company: "Acme", customer_name: user.name },
fallback: fallbacks["support-reply"],
});Run it in CI before the build, so every deploy carries the text that was live then. It reads PROMPTHELM_API_KEY, keys the file by slug, and writes JSON for a .json path. A prompt appears there once it's published; until then, keep its text in the code.
Model settings
A version can carry the model to call it with, its temperature and its output limit, set under the text on the prompt's page. Moving to a cheaper model is then a publish like any other: it rolls back in one click, and an A/B test can tell whether it does as well. Apps on SDK 1.4 or later get them from resolve as config:
const r = await ph.resolve("support-reply", {
vars: { company: "Acme", customer_name: user.name },
fallback: SUPPORT_REPLY,
});
const reply = await openai.responses.create({
model: r.config.model ?? "gpt-5", // your default when none is set
temperature: r.config.temperature,
max_output_tokens: r.config.maxTokens,
input: r.text,
});config holds only the settings set on the page, out of model, temperature and maxTokens, so keep your defaults in the code; when the fallback is served it's empty. PromptHelm doesn't check a model's name with your provider, and one your provider doesn't know fails your calls: try a new model in an A/B test first.
System and user messages
A prompt's text is its system message. It can also hold the user message, for a request your app sends the same way each time with different values. Apps on SDK 1.5 or later get both from resolve, filled in:
const r = await ph.resolve("classify-ticket", {
vars: { product: "Acme", ticket: ticket.text },
fallback: { system: CLASSIFY_TICKET, user: "Ticket: {{ticket}}" },
});
const reply = await openai.responses.create({
model: r.config.model ?? "gpt-5",
instructions: r.system,
input: r.user ?? ticket.text, // null when the version has no user message
});user is null when the live version has none, so your app sends its own, such as what the person typed. get returns the system message only and never needs the user message's variables; older SDKs receive the system message only.
A/B tests
On Pro, a prompt's page can test a new version against the live one: the new version gets a share of the calls and the live version keeps the rest. Apps on SDK 1.3 or later pick the version for each call on your server. resolve says which one a call got, and takes how the call went and what it cost:
const r = await ph.resolve("support-reply", {
vars: { company: "Acme", customer_name: user.name },
fallback: SUPPORT_REPLY,
unit: user.id, // the same user always gets the same version
});
const reply = await openai.responses.create({ model: r.config.model ?? "gpt-5", input: r.text });
r.usage(reply.usage); // tokens, and the call's latency since resolve
r.outcome(userKeptTheReply); // true or false, or a score from 0 to 1
// An outcome that comes later, from any process: keep r.ticket, then
// ph.outcome(ticket, true)Each version brings its own model settings, so a test can compare two models as well as two texts. The prompt's page compares the two versions: how often each succeeded, with a range that stays honest however often you look, and their tokens and latency per call. It says when there's an answer, and emails you once; shipping stays your call. A guarded test stops on its own if the new version is clearly worse.
With a unit, such as a user or conversation id, a user gets the same version every time, and growing the share only moves users to the new version. The unit never leaves your server, and neither does any text: the SDK sends totals only. force: "variant" serves the new version to your own team without counting it, onResolve hands every call's version to your own analytics, and a serverless function should await ph.flush() before it freezes. If the new version uses a variable a call doesn't pass, that call gets the live version.
HTTP API
Any language can fetch the live version with one request:
curl https://prompthelm.app/v1/prompts/support-reply \
-H "Authorization: Bearer $PROMPTHELM_API_KEY"{
"slug": "support-reply",
"version": 4,
"content": "You are the support assistant for {{company}}. …",
"variables": ["company", "customer_name"],
"config": { "model": "gpt-5-mini" }
}Fill in the variables yourself. The ETag header names the live version: send it back as If-None-Match and you get 304 Not Modified until something is published or rolled back, or an A/B test starts, changes or ends. Errors come with status 401 or 404 and a body like { "error": { "code": "not_found", "message": "…" } }.
GET /v1/prompts returns every published prompt of the key's project at once, as { "prompts": [ … ] }, with an ETag of its own.