Variables

Prompts can include placeholders that the SDK fills in at call time. Both the dashboard editor and the SDK use the same regex, so what you see in the variables panel is exactly what pv.get() will substitute.

Syntax

Two equivalent syntaxes are supported:

Variable names match [A-Za-z_][A-Za-z0-9_.-]*. Anything else is left alone - JSON braces, code samples, and matched single-brace literals like { "ok": true } survive untouched.

Substituting

const prompt = await pv.get("onboarding-email", {
  variables: { recipient_name: "Maya" },
});
prompt.source; // "Hi Maya, welcome to PromptVault..."

pv.get() resolves to a Prompt object - the rendered text is on prompt.source (and prompt.systemSource / prompt.userSource / prompt.messages), not the return value itself.

Values can be strings, numbers, or booleans. They're coerced with String(value) before insertion.

await pv.get("usage-summary", {
  variables: {
    user_email: "maya@example.com",
    request_count: 1234,
    is_paid: true,
  },
});

Unknown tokens

Tokens that aren't in variables are left as-is. The SDK doesn't throw, doesn't replace with empty strings, and doesn't warn:

const prompt = await pv.get("template", {
  variables: { name: "Maya" }, // {role} is missing
});
prompt.source; // "Hi Maya, your role is {role}."

This is intentional - many flows fill different subsets of variables in different layers (e.g. a router fills request_id, the worker fills user-specific values). Unknown tokens passing through cleanly lets you compose without reordering.

Detecting variables

Every Prompt carries the names of every token in the original source:

const prompt = await pv.get("onboarding-email", { variables: {...} });
prompt.variables;
// ["recipient_name", "company_name"]

The list is computed from the original source, not the post-interpolation string, so you always know what the template expected. Use this to validate inputs before calling the model:

const required = new Set(prompt.variables);
const provided = new Set(Object.keys(variables));
const missing = [...required].filter((v) => !provided.has(v));
if (missing.length) throw new Error(`Missing variables: ${missing.join(", ")}`);

Disabling interpolation

interpolate: false returns the source untouched, including all tokens:

const raw = await pv.get("onboarding-email", { interpolate: false });
raw.source; // "Hi {{recipient_name}}, welcome to {{company_name}}."

raw.variables still contains the detected names, and raw.source is identical to what was saved in the dashboard. Use this when you want to render variables in a UI, ship the template to a remote system, or interpolate outside the SDK.

Same syntax in the dashboard

The Editor's variables panel uses the same detection rules and lists recognised names as you type, so you can sanity-check tokens before saving.