Core concepts

A short tour of the ideas behind PromptFlip. Everything here applies whether you use an SDK or call the HTTP API directly.

Prompts and keys

A prompt is referenced by a stable key such as welcome-message. Your code fetches by key and never hardcodes the prompt text — that text lives in the registry, where it can change without a deploy.

Versions

Each prompt has an ordered history of versions. Publishing a new version changes what get() serves immediately server-side — the only delay is however long your own SDK instance caches a prior fetch (see Guarantees for the default cache behavior). Because the key stays the same, your code never changes when a prompt does.

Environments

An environment (for example prod or staging) lets you serve different versions of the same key to different deployments. Set it once when you construct the client and every fetch is scoped to it.

A/B experiments

An experiment splits traffic across two or more variants of a prompt. Pass an assignment_key (such as a user id) and the same caller always gets the same variant — sticky assignment. Report outcomes, then promote the winner from the dashboard.

Inputs and variables

Prompts use two kinds of placeholder, and the difference matters:

• [[inputs]] are filled client-side from the inputs you pass to get(). They are safe to include in a fallback.
• {{variables}} are filled server-side and may hold secrets. They are treated as plain text in a fallback — never put them there.

Stored prompt:
  "Hi [[name]], your [[plan]] plan renews on {{renewal_date}}."

[[name]], [[plan]]   inputs — you pass these from your app
{{renewal_date}}     variables — resolved on the server

Fallbacks

Every get() takes a fallback template. When the service is unreachable and nothing usable is cached, the SDK renders the fallback — filling its [[inputs]] so the end user sees the same string online or offline. This is why the serving path never throws.

Telemetry and runs

Each successful fetch corresponds to a run. Report results against it — tokens, latency, plus any custom numeric or boolean metric — to compare versions and decide experiments. Reporting is always optional and never blocks your request.