# PromptHelm quickstart

Move one prompt out of your code into PromptHelm, fetch it at runtime with the TypeScript SDK or one HTTP request, and change it later without a deploy. The SDK needs Node.js 18 or later; any other language uses the HTTP API. The app keeps calling its own LLM provider: PromptHelm only supplies the text.

Human-readable version: https://prompthelm.app/quickstart

## Notes for coding agents

- Keys can't change prompts: there is no API to create, edit or publish them (the SDK only fetches them, and sends A/B test totals): the user adds and publishes each prompt in the dashboard (https://prompthelm.app/projects). After changing the code, give the user every slug with its text, variables marked, to paste and publish.
- Moving a hard-coded prompt: create one shared `PromptHelm` client, replace the prompt with `await ph.get("<slug>", { vars, fallback })`, keep the original text as the `fallback`, and pass every value the prompt interpolates in `vars`. The stored version marks those values as `{{name}}`. The fallback may use the same `{{name}}` variables; `get` fills in either text.
- `new PromptHelm()` throws when no API key is set (`PROMPTHELM_API_KEY` or `apiKey`). Where code runs without the key, such as tests or a build, set one or create the client where it's first used.
- Until a prompt is published, the API answers 404 and `get` returns the fallback.
- To keep fallbacks current, `npx @prompt-helm/sdk pull --out <file>` (it reads `PROMPTHELM_API_KEY`) writes every published prompt to one file keyed by slug; pass `fallbacks["<slug>"]` as the fallback. A prompt is in that file only once it's published, so keep the hard-coded text as its fallback until then.
- Keep the key on the server. Never put it in code that runs in a browser or a mobile app.

## 1. Create an account and a project

Sign up at https://prompthelm.app/sign-up with an email link (no password), then create a project. One project per app keeps its keys and prompts apart.

## 2. Add the prompt

Choose New prompt, give it a slug and paste the prompt the app sends today. The slug is the name the code asks for: lowercase letters and digits in words joined by single hyphens, up to 64 characters, such as `support-reply`. Mark each part that changes per request as a variable in double braces:

```text
You are the support assistant for {{company}}. Answer {{customer_name}}'s question in two or three sentences.
```

Variable names start with a letter or an underscore, followed by letters, digits or underscores. Review the diff and publish (Cmd+Enter, or Ctrl+Enter on Windows and Linux).

## 3. Create an API key

Open API keys and create a key for this app. It's shown once, so put it in the server's environment straight away:

```sh
PROMPTHELM_API_KEY=ph_…
```

A key reads the published prompts of its own project.

## 4. Install the SDK

```sh
npm install @prompt-helm/sdk
```

Or `pnpm add`, `yarn add` or `bun add`. It runs on Node.js 18 and later, from ESM or CommonJS, with no dependencies.

## 5. Fetch the prompt

```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 on the server. Their values never reach PromptHelm.

## 6. Change it without a deploy

Edit the prompt in the dashboard and publish. The app serves the new version after its next refresh. To go back, open History and make an older version live; the app follows the same way.

## Client options

Pass these to `new PromptHelm({ … })`. Every one is optional when the environment variables are set.

| Option | Default | What it does |
| --- | --- | --- |
| `apiKey` | `PROMPTHELM_API_KEY` | Your project's API key. |
| `baseUrl` | `PROMPTHELM_BASE_URL, then https://prompthelm.app` | Where prompts are fetched from. |
| `ttl` | `60000` | How long, in ms, a prompt is served before the SDK checks for a newer version. |
| `timeout` | `3000` | How long, in ms, one request may take. |
| `onError` | `console.warn` | Called with the error and the slug whenever a fallback or a cached prompt was served instead of failing. |
| `reportFallbacks` | `true` | 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. |
| `reportResults` | `reportFallbacks` | 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. |
| `onResolve` | `none` | 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. |
| `fetch` | `global fetch` | Your own fetch, for tests or a proxy. |

## Errors

Failures are `PromptHelmError`s with a `code`, a `message` and, for HTTP errors, a `status`. Without a fallback, `get` throws them; with one, `onError` receives them.

| Code | When |
| --- | --- |
| `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. |

After the first successful fetch, a failed background refresh keeps serving the cached prompt and tries again after one ttl.

## Fallbacks that stay current

A fallback is only as good as its text, and a copy kept in the code drifts from what's published. Write every published prompt to one file instead, and pass it as the fallback:

```sh
npx @prompt-helm/sdk pull --out src/prompthelm.fallbacks.ts
```

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

```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 (`model`, `temperature`, `maxTokens`), so keep the defaults in the code; when the fallback is served it's empty. PromptHelm doesn't check a model's name with the provider, and one the provider doesn't know fails the 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 the app sends the same way each time with different values. Apps on SDK 1.5 or later get both from `resolve`, filled in:

```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 the 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, the prompt's page can test a new version against the live one: the new version gets a share of the calls (20% by default) and the live version keeps the rest. Apps on SDK 1.3 or later pick the version for each call on their own server; older ones keep serving the live version. Use `resolve` to learn which version a call got, and report how the call went and what it cost:

```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.
- Pass a `unit`, such as a user or conversation id, and that unit gets the same version every time; growing the share only moves units to the new version. Without one, each call is picked at random. The unit never leaves your server.
- If the new version uses a variable the call doesn't pass, that call gets the live version and `onError` receives `missing_variables`.
- `r.outcome(value)` takes true or false, or a score from 0 to 1; `r.usage(response.usage)` reads tokens from OpenAI, Anthropic, Vercel AI SDK or Gemini usage objects and times the call. For an outcome that comes later (a purchase days on), keep `r.ticket` and call `ph.outcome(ticket, true)` from any process.
- The SDK sends totals only (calls per version, outcomes, tokens, durations) to `POST /v1/reports` within a ttl; `reportResults: false` turns it off, and a serverless function should `await ph.flush()` before it freezes. `force: "variant"` serves the new version to the team without counting it; `onResolve` gives every call's version to the app's own analytics.
- The prompt's page says whether the new version is ahead, behind or the same within the smallest difference that matters, with an interval that stays valid however often it's looked at, and shows tokens and latency per version. Shipping stays the user's call; a guarded test stops on its own if the new version is clearly worse.

## HTTP API

Any language can fetch the live version with one request:

```sh
curl https://prompthelm.app/v1/prompts/support-reply \
  -H "Authorization: Bearer $PROMPTHELM_API_KEY"
```

```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. `config` holds the live version's model settings, only those set. When the live version has a user message, the body carries it as `user: { content, variables }`; `content` is always the system message. During a test the body also carries `experiment: { id, weight, variant: { version, content, variables, user, config } }`; to split calls like the SDK, give the variant the units whose bucket, the 32-bit FNV-1a hash of the UTF-8 bytes of `<experiment id>:<unit>` modulo 100, is below `weight`. 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.
