> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wardin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompts

> A versioned prompt registry with pinned labels and a metered playground — then tag production requests to the exact version that served them.

Prompt text drifts — someone tweaks it in a chat window, ships it, and nobody can say which version produced last Tuesday's outputs. The **Prompt Registry** gives every prompt a name, an append-only version history, and named labels (`production`, `staging`, …) that point at a specific version. Runs through the built-in playground are metered like any other gateway traffic, and production requests can carry the prompt's identity all the way into your cost and evidence data via a request header.

## Prompts, versions, and labels

* A **prompt** is a named template (`{{variable}}` placeholders supported) — unique per tenant by name.
* A **version** is immutable once created: editing a prompt appends version `N+1`, it never rewrites `N`. History is preserved on purpose — a version an old receipt cites stays exactly as it was.
* A **label** is a named pointer (e.g. `production`, `staging`) at a specific version, upsertable at any time. Labels are how you promote a version without changing any caller's config — the caller resolves the label, not a hardcoded version id.

```bash theme={null}
# Create a prompt (also creates version 1)
curl -X POST https://api.wardin.ai/v1/prompts \
  -H "Authorization: Bearer wardin_sk_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support reply template",
    "description": "First-response drafts for the support team",
    "content": "You are a helpful support agent. Reply to: {{message}}"
  }'

# Append a new version
curl -X POST https://api.wardin.ai/v1/prompts/versions \
  -H "Authorization: Bearer wardin_sk_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "promptId": "PROMPT_UUID", "content": "Updated system prompt text" }'

# Point "production" at that new version
curl -X POST https://api.wardin.ai/v1/prompts/labels \
  -H "Authorization: Bearer wardin_sk_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "promptId": "PROMPT_UUID", "label": "production", "versionId": "VERSION_UUID" }'
```

Full endpoint references: [`GET /v1/prompts`](/api-reference/prompts/list), [`POST /v1/prompts`](/api-reference/prompts/create), [`GET /v1/prompts/{promptId}/versions`](/api-reference/prompts/versions-list), [`POST /v1/prompts/versions`](/api-reference/prompts/versions-append), [`POST /v1/prompts/labels`](/api-reference/prompts/labels).

A caller that only knows the label — not a specific version id — can resolve it at read time:

```bash theme={null}
curl "https://api.wardin.ai/v1/prompts/PROMPT_UUID/label/production" \
  -H "Authorization: Bearer wardin_sk_ADMIN_KEY"
# → { "promptId", "versionId", "version", "content" }
```

Full endpoint reference: [`GET /v1/prompts/{id}/label/{label}`](/api-reference/prompts/resolve-label).

## The playground (runs are metered)

Console → Prompts includes a playground: pick a version, fill in `{{variable}}` values, and run it. The run goes through the real gateway (`POST /v1/messages`, currently the `claude-3-5-haiku` model), so it consumes real budget and is priced the same as any other request — it is not a free sandbox. Each run is logged with its input/output token split and cost, and per-prompt stats (total runs, tokens, cost, per-version breakdown) are available from the Analytics tab on each prompt.

```bash theme={null}
curl -X POST https://api.wardin.ai/v1/prompts/run \
  -H "Authorization: Bearer wardin_sk_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "promptId": "PROMPT_UUID",
    "versionId": "VERSION_UUID",
    "variables": { "message": "My invoice looks wrong" }
  }'
# → { "output", "inputTokens", "outputTokens", "costUsd" }
```

Full endpoint reference: [`POST /v1/prompts/run`](/api-reference/prompts/run).

## Production tagging

Outside the playground, tag any real gateway request with the prompt (and optionally the exact version) that generated it by sending the request-attribution headers documented in [Gateway → Connect](/gateway/connect#request-attribution-headers):

```bash theme={null}
curl https://gw.wardin.ai/v1/messages \
  -H "Authorization: Bearer wardin_sk_YOUR_KEY" \
  -H "X-Wardin-Prompt-Id: PROMPT_UUID" \
  -H "X-Wardin-Prompt-Version-Id: VERSION_UUID" \
  -H "Content-Type: application/json" \
  -d '{ "model": "claude-3-5-sonnet-20241022", "max_tokens": 1024, "messages": [...] }'
```

`X-Wardin-Prompt-Version-Id` is optional — send just `X-Wardin-Prompt-Id` to attribute a request to the prompt without pinning a version. Either way, the ids are carried through to the usage event, so per-prompt spend and run counts reflect real production traffic, not just playground runs.

<Note>
  Production tagging is separate from the labels feature above: the header carries whatever prompt/version id you send — it does not resolve a label server-side. If your client only knows a label name, resolve it first with `GET /v1/prompts/{id}/label/{label}` and send the resolved `versionId` in the header.
</Note>

## Where to see it

Console → **PLATFORM → Prompts** lists every prompt with its labels, lets you create/append/label/run from the same screen, and shows per-prompt run history and analytics.