Prompts
Inline Prompt
Prompts written and versioned in Multi-Router, through the dashboard or the API.
An inline prompt is a prompt whose content is stored in Multi-Router. It is created and edited on the Prompts page or with the API, and every saved change becomes a new numbered revision, so the full history of the prompt stays available and a router can be pinned to any revision. Inline prompts have ids that start with ip_, such as ip_6Rt2Kw9QmD.
Fields
An inline prompt has the following fields:
| Field | Description |
|---|---|
id | The prompt id, starting with ip_. Assigned by Multi-Router and fixed for the life of the prompt. |
name | A display name of up to 80 characters, such as support-triage. Names can be changed at any time. |
type | text or chat. Chosen when the prompt is created and fixed afterwards. |
body | The content of the current revision: a string for a text prompt, or an array of messages for a chat prompt. |
variables | The variable names found in the body, in the order they first appear. |
version | The number of the latest revision. |
etag | The prompt's ETag, sent in If-Match to change it safely. |
tags | Tag names, changed through the tags endpoints. |
created_at | When the prompt was created. |
updated_at | When the prompt was last renamed or given a new revision. |
Revisions
A revision is a saved version of a prompt's content. Revisions are numbered from 1 in the order they are saved, and a saved revision is never changed, so revision 3 always has the same content. Each revision records:
| Field | Description |
|---|---|
version | The revision number. |
message | An optional note of up to 200 characters describing the change, such as Fix typo in greeting, entered as the title when saving in the dashboard. The first revision saved in the dashboard is titled Initial. |
author | The person who saved the revision in the dashboard, or the API key that saved it through the API. |
created_at | When the revision was saved. |
A change to the content saves a new revision, and a change to the name alone renames the prompt with no new revision. To return to earlier content, open the revision in History, copy its content, and save it as a new revision, or pin the routers that use the prompt to the earlier revision. Through the API, POST /v1/prompts/{id}/versions/{version}/restore saves an earlier revision as a new revision. See Prompt Binding.
Creating in the dashboard
An inline prompt is created on the Prompts page:
- Open Prompts in the top navigation, select New Prompt, and choose New inline prompt.
- Choose Text or Chat, and enter a name of up to 80 characters. The page warns when another prompt in the organization already has the name.
- Write the content. In a text prompt, wrap variables in double curly braces, such as
{{product}}. In a chat prompt, add messages with the System, User and Assistant buttons. - Select Save · revision 1.
Editing in the dashboard
The prompt's page shows its name, a type pill such as text or chat · 4 msgs, the current revision such as rev 3, and when it was last edited. It has two tabs and a side panel:
| Area | Contents |
|---|---|
| Content | The content of the current revision. Edit opens the editor. |
| History | Every revision with its number, title, author and date. Selecting a revision shows its content. |
| Variables | The variables found in the content, or No variables detected. |
Edit opens the editor with an optional revision title, and Save changes saves the content as the next revision. Rename changes the name with no new revision. The chat editor shows one card per message: messages are added with the System, User and Assistant buttons, reordered by dragging, and removed after a confirmation. Edit raw JSON switches to the message array as JSON, and Back to structured editor returns to the cards. A Structural issue banner describes any message order that breaks the chat rules, and the prompt saves once the issue is fixed. See Prompt Type.
Managing with the API
Inline prompts are created with POST /v1/prompts. An optional Idempotency-Key header makes a retried request create the prompt once. A text body is a JSON string, and a chat body is a JSON array of messages:
PATCH /v1/prompts/{id} changes the name or body sent. A changed body saves a new revision, a changed name alone renames the prompt, and the type is fixed. An If-Match header with the prompt's ETag refuses the change with 412 if another change landed first.
The revision history is read and restored with these endpoints:
| Endpoint | Returns |
|---|---|
GET /v1/prompts/{id}/versions | The revisions, newest first, each with version, author, message and created_at. |
GET /v1/prompts/{id}/versions/{version} | One revision, including its body. |
POST /v1/prompts/{id}/versions/{version}/restore | Makes an earlier revision current by saving it as a new revision. Takes no body. |
Deleting
Deleting an inline prompt removes the prompt and all of its revisions. A prompt is deleted only when no router is bound to it; while routers use it, the delete is refused with prompt_in_use and the routers are listed, so they can be bound to another prompt or unbound first. In the dashboard, Delete asks for confirmation before removing the prompt. With the API, the prompt is deleted with DELETE /v1/prompts/{id}:
Errors
Creating, editing and deleting inline prompts return the following errors:
| Error | Status | Cause |
|---|---|---|
idempotency_key_reused | 409 | The Idempotency-Key was used before with a different request. |
idempotency_in_progress | 409 | A request with the same Idempotency-Key is still being processed. |
missing_field | 400 | The type, name or body is missing. |
invalid_field | 400 | A field has the wrong shape, the name or content is over its limit, or a chat body breaks the chat rules. |
invalid_json | 400 | The request body is not valid JSON. |
unknown_field | 400 | An edit sends a field prompts do not have, such as description. |
field_read_only | 400 | An edit sends a read-only field, such as id, type or version. current_version and variables return unknown_field. |
use_sub_collection | 400 | An edit sends tags. Tags change through /v1/prompts/{id}/tags. The valid field of the error lists that path template; {id} is not replaced with the object id. |
version_conflict | 412 | The If-Match ETag is stale. The response carries the current prompt. |
revision_conflict | 409 | Another change saved a revision at the same moment. Read the prompt and retry. |
prompt_not_found | 404 | No prompt with that id exists in the organization. |
revision_not_found | 404 | The prompt has no revision with that number. |
prompt_in_use | 409 | A delete names a prompt that routers are bound to. The message lists the routers. |
source_read_only | 409 | An edit or delete names a GitHub prompt, which changes only through its repository. |