Prompts

The Prompts screen lets you store versioned prompt templates with variables, read their versions and render them with values. Portal path: /data/prompts. Developers and tenant administrators use it to share prompts between agents and applications.

What the screen shows

The Prompts table lists the prompts of the tenant by name: Name, Latest version, Description, Updated.

The New prompt form has Name (required), Template (required, example Summarize {{document}} in {{language}}.), Variables (comma separated, for example document, language), Description and Model hint. Each variable is sent as required.

The row menu offers Versions and Render; their answers open in a side panel as JSON.

Actions

Button or action	What it does	API call	Roles
Refresh icon	Reloads the list	`GET /v1/prompts`	any tenant user
New prompt > Create	Creates the prompt, or publishes a new version when the name exists (an identical template is not duplicated)	`POST /v1/prompts`	`tenant_admin`, `developer`
Versions (row menu)	Shows every version with its template, variables, model hint and digest	`GET /v1/prompts/{name}/versions`	any tenant user
Render (row menu)	Opens a dialog with Variables (JSON, required), then renders the latest version	`POST /v1/prompts/{name}/render`	any tenant user

Roles

The portal shows every button. In services/control-plane/src/eai/domains/prompts/__init__.py publishing needs tenant_admin or developer; reading and rendering need a user of the tenant.

Typical tasks

Publish a prompt and a new version

Create the prompt. The name is the stable key that agents reference. Click New prompt, fill Name (lowercase, digits, ., _, -), Template and Variables, then Create.

Expected result: the toast "Created" and the row with Latest version 1.

If it fails: template_error means a placeholder is unbalanced or not declared in Variables.
Publish a change. Create the prompt again with the same Name and the new Template.

Expected result: Latest version goes to 2; the same template again changes nothing.

If it fails: forbidden means you are neither tenant_admin nor developer.

Check the text sent to the model

Render the prompt. Rendering applies the values to the latest version. Open the row menu, choose Render and type the values:
```
{"document": "the attached report", "language": "English"}
```
Expected result: the panel shows text, chars, estimated_tokens, version and digest.

If it fails: missing_variables lists the required variables that have no value.

Troubleshooting

Symptom	Cause	Fix
`forbidden` (403) on Create	You are neither `tenant_admin` nor `developer`	Ask for the `developer` role
`invalid_request` (400) with `name`	The name has capitals, spaces or other characters	Use lowercase letters, digits, `.`, `_` and `-`
`template_error` (422)	Unbalanced placeholder, invalid variable type or undeclared variable	Declare every `{{variable}}` in Variables
`missing_variables` (422) on Render	A required variable has no value	Add it to the JSON of Variables
`not_found` (404) with `prompt_version`	The requested version does not exist	Read Versions first

What the screen shows​

Actions​

Roles​

Typical tasks​

Publish a prompt and a new version​

Check the text sent to the model​

Troubleshooting​

Related pages​