Prompt templates

The Prompt Repository lets operators add consistent messages around a caller’s conversation without changing the client. A template contains ordered decorators and an optional set of variables. Each saved version is immutable, so the live prompt can always be traced to the exact content and scope that produced it.

Create a template#

Open Prompt Repository in the dashboard and create a template. Its slug is the stable identity; the name and description explain its purpose to other operators.

Add one or more decorators:

• Role controls whether the rendered message is sent as system, assistant, or user.
• Position places the message before or after the caller’s original messages.
• Content accepts declared variables in {{ variable_name }} form.

Variable names start with a letter or underscore and contain only letters, digits, and underscores. A variable is either required or optional. The caller must send a required variable on every request the template applies to, even when no decorator uses it yet. An optional variable may have a default value; when the caller leaves it out, a placeholder renders the default, or nothing at all if there is none. A variable cannot be both required and defaulted. Use the live preview’s sample values to inspect the rendered messages; samples remain in the browser and are not saved.

Assign scopes#

A version can be assigned to the entire organization, the current project, an individual route, or a virtual key. Leave its scope list empty to save it without deploying it anywhere.

The control plane validates a version when it is created, through the API as well as the dashboard, and answers HTTP 400 with every problem it found: a variable that is both required and defaulted, a variable declared twice, a placeholder with no declared variable, a malformed placeholder, or no decorators at all. Nothing is stored until the content is valid.

Scope assignment belongs to the version. Once a version is published, both its content and scopes remain immutable. Create a new draft to make a change.

Every published template whose scopes match a request applies to it, in slug order. No scope takes precedence over another: a route-scoped template and a project-scoped one both decorate a request that matches both.

Send variables from the client#

Callers pass variable values in a rolter_template_vars object in the request body, beside model and messages. Every value is a string. The gateway removes the object before it forwards the request upstream, including when no template applies to the route.

{  "model": "support",  "messages": [{ "role": "user", "content": "My order has not arrived." }],  "rolter_template_vars": {    "customer_name": "Aster Labs"  }}

A placeholder takes the caller’s value first and the variable’s default second; an optional variable with no default renders as an empty string. The gateway refuses the request with HTTP 400 and the code invalid_prompt_template when:

• the request does not send a variable the template declares required;
• the request sends a variable that no template applied to it declares;
• rolter_template_vars is not an object of strings, a value is longer than 4 KiB, or a rendered decorator is longer than 16 KiB.

{  "error": {    "message": "missing required variable 'ticket_id' for prompt template '<org id>:support-concierge'",    "type": "invalid_request_error",    "param": null,    "code": "invalid_prompt_template"  }}

The preview panel in the dashboard shows the rolter_template_vars object for the draft you are editing, filled in with your sample values or the defaults.

Publish and roll back#

Save as new draft creates the next immutable version. A version newer than the live one offers Publish, in the workbench header and in the history rail; an older one offers Roll back. Both change the template’s live-version pointer rather than the saved version, and the audit log records each under its own name. When nothing is live yet, every version offers Publish.

Both open the same confirmation before anything changes. It lists:

• the scopes the version applies to, marking the ones the live version does not reach;
• the variables a request in those scopes must send, marking the ones the live version did not need;
• the variables the live version declares and this one does not.

Each of these can refuse requests that work today, so the dialog warns when one applies. It never blocks the change, because a roll back during an incident should not wait on a warning. A version with no scopes applies to no requests, and the dialog says that instead.

After a roll back, the newer versions stay in history and can be published again.

Compare a version with the live one#

A selected version that is not the live one offers Compare with live vN in the workbench header. The comparison lists the variables that were added, removed or changed, and shows the decorators as a line diff, inline or side by side. Removed lines and added lines are marked with - and + as well as colour. The publish and roll back dialogs carry the same comparison under Changes from live vN, folded behind Show changes, with the number of differences shown first.

Each version in the history rail also lists the scopes it is assigned to, by name. The control plane does not record who created a version yet, so the rail shows no author.

The workbench marks Unsaved changes while the draft differs from the version it was opened from. Selecting another template or version, creating a template, or leaving the screen asks whether to discard the edits first, and Cancel keeps them. When you cancel after creating, the new template still exists and is listed; it is only not selected.

On a phone the version history is a single line above the workbench showing the selected version and how many there are; tap it to open the list.

Rename and delete#

Rename changes a template’s name and description. The slug is the stable identity callers route through, so it never changes, and versions and scopes are left untouched.

Delete removes the template together with every version, scope and sample it holds. If a version is live, traffic routed through the template starts failing as soon as it is gone, so the dialog asks you to type the template’s slug back before it will proceed. There is no undo.