Skip to content

Quickstart

Your first live prompt.

Move one prompt out of your code, then change it without a deploy. You need an app on Node.js 18 or later that calls an LLM.

6 stepsNode.js 18+Any LLM provider

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. 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. 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. 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:

    .env
    PROMPTHELM_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. 4

    Install the SDK

    $ npm install @prompt-helm/sdk

    It runs on Node.js 18 and later, from ESM or CommonJS, with no dependencies.

  5. 5

    Fetch the prompt

    Ask for the prompt where your code used to hard-code it:

    app.ts
    import { 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, get doesn't throw. A timeout, a network error, a bad key, a missing prompt or a missing variable returns the fallback and calls onError.
    • Variables are filled in here, on your server. Their values never reach PromptHelm.
  6. 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.DefaultPROMPTHELM_API_KEY
baseUrl
Where prompts are fetched from.DefaultPROMPTHELM_BASE_URL, then https://prompthelm.app
ttl
How long, in ms, a prompt is served before the SDK checks for a newer version.Default60000
timeout
How long, in ms, one request may take.Default3000
onError
Called with the error and the slug whenever a fallback or a cached prompt was served instead of failing.Defaultconsole.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.Defaulttrue
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.DefaultreportFallbacks
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.Defaultnone
fetch
Your own fetch, for tests or a proxy.Defaultglobal 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:

Terminal
npx @prompt-helm/sdk pull --out src/prompthelm.fallbacks.ts
app.ts
import { 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:

app.ts
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:

app.ts
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:

app.ts
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:

Terminal
curl https://prompthelm.app/v1/prompts/support-reply \
  -H "Authorization: Bearer $PROMPTHELM_API_KEY"
200 OK · application/json
{
  "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.