Variables

Variables let you create dynamic, reusable prompts by inserting placeholders that get replaced with actual values at fetch time. This means a single prompt template can serve many different contexts.

Syntax

Use double curly braces to define a variable:

Hello {{user_name}}, welcome to {{company_name}}!

Variable names must be alphanumeric characters and underscores (matching the \w+ pattern):

How interpolation works

When you fetch a prompt via the API, you can pass variable values in two ways:

Via query parameters (GET)

Pass variables as query parameters on a GET request:

curl -H "Authorization: Bearer fp_prod_xxx" \
  "https://www.fetchprompt.com/api/v1/prompts/welcome-message?user_name=Sarah&company_name=Acme"

Via JSON body (POST)

Pass variables in a JSON body on a POST request:

curl -X POST \
  -H "Authorization: Bearer fp_prod_xxx" \
  -H "Content-Type: application/json" \
  -d '{"user_name": "Sarah", "company_name": "Acme"}' \
  https://www.fetchprompt.com/api/v1/prompts/welcome-message

Pass variables as a flat JSON object (no wrapper key). Both methods produce the same result. Use POST when you have many variables or when variable values contain special characters that would need URL encoding.

Missing variables

If your prompt contains variables that aren't provided in the request, FetchPrompt handles it gracefully:

• The unreplaced {{variable}} placeholders remain in the content as-is.
• The response includes a missing_variables array listing which variables were not provided.

Example: Prompt content is Hello {{user_name}}, your order {{order_id}} is ready.

Request with only user_name:

curl -H "Authorization: Bearer fp_prod_xxx" \
  "https://www.fetchprompt.com/api/v1/prompts/order-ready?user_name=Sarah"

Response:

{
  "slug": "order-ready",
  "name": "Order Ready Notification",
  "content": "Hello Sarah, your order {{order_id}} is ready.",
  "version": 2,
  "environment": "prod",
  "missing_variables": ["order_id"]
}

This non-strict behavior lets you progressively fill in variables or handle missing ones in your application logic.

Auto-detection in the editor

The prompt editor automatically scans your content for {{variable}} patterns and displays detected variables as badges below the text area. This gives you a quick visual reference of all the variables your prompt expects.

As you type, the variable badges update in real time.

Best practices

Use descriptive names — Prefer {{customer_first_name}} over {{name}}. Clear variable names make prompts self-documenting.

Be consistent with naming — Pick a convention (e.g., snake_case) and stick with it across all your prompts.

Document expected variables — Include a comment at the top of complex prompts listing expected variables:

{{! Variables: user_name, company_name, support_tier, language }}
You are a {{support_tier}} support agent for {{company_name}}.
The customer's name is {{user_name}}.
Respond in {{language}}.

Check for missing variables — Always inspect the missing_variables field in the API response. Log a warning if variables are unexpectedly missing.

const { content, missing_variables } = await response.json();

if (missing_variables?.length > 0) {
  console.warn("Missing prompt variables:", missing_variables);
}

Use POST for complex values — If variable values contain special characters, newlines, or are very long, use the POST method with a JSON body to avoid URL encoding issues.