Concepts

An engine is one place in your product that needs a prompt. A support-reply generator is an engine. A ticket summarizer is a different engine. A spam classifier is a third.

Think of it as a stable address. Your code hardcodes the engine ID once and never changes it again — everything that varies happens behind it. An engine holds many prompts, but exactly one of them is live at a time.

A prompt is the text itself, and it is versioned. Editing a prompt that is live doesn't overwrite it — it creates a new version, and the old one stays exactly as it was. Nothing you have ever shipped gets silently rewritten.

Versions are labelled major.minor, like 2.1. The major is the prompt's number within the engine; the minor counts versions within it. Versions can branch: fork 1.1 to try a different approach and you get siblings that both descend from it. The whole family is a lineage.

Engine 12  "Support reply"
│
├── 1.0  ─────────────────────────────  inactive
│   └── 1.1 ────────────────────────── inactive
│       ├── 1.2  ─────────────────────  ACTIVE  ← what the API returns
│       └── 1.3  ─────────────────────  draft
│
└── 2.0  ─────────────────────────────  draft
    └── 2.1 ────────────────────────── inactive

A version is in one of three states. Draft is being worked on and can be edited in place. Active is the one the API serves — at most one per engine, ever. Inactive was live once and no longer is. Editing an active or inactive version forks a new draft rather than changing history.

Activating is the deploy. It is the only action that changes what your production traffic gets, it takes effect on the very next API call, and it needs no involvement from you or your code.

Activating a version automatically deactivates whatever was live before, so an engine can never have two active prompts. Rolling back is the same action pointed at the older version — nothing was deleted, so it is always available.

This is why version comes back in every response. Log it alongside your model output and a change in quality can be traced to the exact prompt that caused it.

Prompts contain placeholders written as {{customer_name}}. You send values at call time and we substitute them.

The list you get from List variables is always exactly what the live prompt references — no stale entries, nothing undeclared.

At call time we are deliberately lenient: a placeholder you send no value for resolves to empty and is named back to you in missing_variables, rather than failing the request. One missing value degrades one call instead of taking a feature down.

Prompts come in kinds. A plain template is raw text. A Kitchen prompt is assembled from structured sections into a system and a user message, for a specific provider.

The API hides that difference completely. Every response has the same fields in the same places — messages, text, version, mode, missing_variables — whatever kind of prompt is live. messages is always a system entry followed by a user entry, even when the system one is empty, so it never changes length underneath you. Nothing in the response says which kind of prompt produced it, because you never need to know.

The one distinction the API does surface is mode: a text prompt and an image prompt go to genuinely different APIs on your side, and no response shape can paper over that. Plain templates report null — they carry no provider, so which kind of model they're for is unknown to us.