Prompt Manager | Documentation Center

Endpoints

List Prompts

GET /api/v2/prompts

Business impact: Powers the repository grid, version history, and selected prompt drawer. Enables operators to audit which prompt is live and preview content before deploying.
Developer details: Add ?json=true or Accept: application/json to receive the manifest bundle used by the SPA (prompts, configured defaults, selected prompt, storage metadata). Optional query params: prompt_id, prompt_type load a specific prompt payload.

Example Response

{
    "prompts": {
        "system_prompts": [
            {
                "id": "7e1a...",
                "name": "assistant_default.j2",
                "metadata": {"label": "Default", "prompt_tag": "default"},
                "is_current": true
            }
        ],
        "response_templates": [
            {
                "id": "9c4b...",
                "name": "plain_answer.j2",
                "metadata": {"label": "Plain"}
            }
        ],
        "experiments": []
    },
    "configured_defaults": {
        "system_prompts": ["assistant_default.j2"],
        "response_template": "plain_answer.j2"
    },
    "effective": {
        "system_prompt": "You are the nightly assistant...",
        "response_template": "{{ answer }}"
    },
    "source": "filesystem",
    "versions_by_type": {
        "system": {"entries": [...]},
        "response": {"entries": [...]} 
    }
}

Create / Update Prompt (Repository save)

POST /api/v2/prompts

Business impact: Lets prompt authors create experiments or new baselines without shell access.
Developer details: Submit form data or JSON with new_prompt_name, new_prompt_type, new_prompt_content. The repository appends a versioned file (auto .j2 suffix) and returns saved=true on redirect.

Request Example

{
    "new_prompt_name": "summarize_baseline",
    "new_prompt_type": "response",
    "new_prompt_content": "Summarize the following text: {{ input }}"
}

Update Default Prompt (Editor save)

POST /api/v2/prompts

Business impact: Single action to edit copy, tag the release, and put it live. Adds traceability via metadata notes.
Developer details: Submit the appropriate form fields (system_prompt, system_prompt_label, system_prompt_make_default=on, etc.). The service returns the new manifest entry, promotes it to current_id, reloads factories, and redirects with saved=true&default_set=true.

See Saving defaults from the editor for end-to-end examples.

Prompt metadata / maintenance actions

All map to POST /api/v2/prompts with action:

Action	Business impact	Developer details
`update_prompt_metadata`	Adjust labels, tags, notes without editing content.	Provide `prompt_identifier`, `prompt_type`, and `metadata_*` fields; response redirects with `metadata_saved=true`.
`rename_prompt`	Clarify filenames for audits while preserving history.	Requires `new_name`; works for system/response/experiments. Suffix automatically appended.
`delete_prompt`	Retire experiments or cleanup storage.	Removes file/blob, updates manifest; current default falls back to next entry.
`make_default_prompt`	Promote existing version from repository.	Accepts manifest `id`, filename, or path. Redirect adds `default_set=true`.

Metadata update example

curl -X POST "https://yourhost/api/v2/prompts" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data "action=update_prompt_metadata" \
    --data "prompt_type=system" \
    --data "prompt_identifier=assistant_default.j2" \
    --data "metadata_label=Assistant default (Q4)" \
    --data "metadata_prompt_tag=default" \
    --data-urlencode "metadata_notes=Deployed after nightly QA"

import os
import requests

base_url = os.getenv("RAG_API_BASE", "https://yourhost/api/v2")
    "status": "success",

    "prompt_id": "uuid"
        "action": "update_prompt_metadata",
        "prompt_type": "system",
        "prompt_identifier": "assistant_default.j2",
        "metadata_label": "Assistant default (Q4)",
        "metadata_prompt_tag": "default",
        "metadata_notes": "Deployed after nightly QA",
}

headers = {
        "Authorization": f"Bearer {token}" if token else None,
        "Content-Type": "application/x-www-form-urlencoded",
}
headers = {k: v for k, v in headers.items() if v}

resp = requests.post(f"{base_url}/prompts", data=payload, headers=headers, allow_redirects=False)
resp.raise_for_status()
print(resp.headers.get("Location"))

List Prompt Versions

GET /api/v2/prompts?json=true&prompt_type=system

Business impact: Feed version history cards with sorted entries, showing saved_by, tags, and notes.
Developer details: The JSON payload includes versions_by_type.system.entries with is_current, metadata, and storage info. Clients can sort or filter before rendering.

Revert Prompt to Previous Version

POST /api/v2/prompts with action=make_default_prompt

Business impact: Roll back to a known good version rapidly from the repository list or version history.
Developer details: Provide prompt_type and prompt_identifier (record ID, filename, or path). The manifest updates current_id, caches refresh, and redirect includes default_set=true. }

### List Prompt Versions
`GET /prompts/versions?type=system&name=system_prompt.j2`
- Returns available versions for a given prompt

#### Example Response
```json
{
    "entries": [
        {"name": "system_prompt.j2", "version": "20240601-120000", "is_current": true},
        {"name": "system_prompt.j2", "version": "20240530-090000", "is_current": false}
    ]
}

Revert Prompt to Previous Version

POST /prompts/revert - Revert a prompt to a previous version

Request Example

{
    "type": "system",
    "name": "system_prompt.j2",
    "version": "20240530-090000"
}

Response Example

{
    "status": "success",
    "reverted_to": "20240530-090000"
}

Saving defaults from the editor

Business impact

Editing the "Update current default" forms now versions the prompt and makes it live in a single save, so hand-offs between authors and operators disappear.
Status pills reflect saved=true&default_set=true, letting reviewers confirm the switch without touching the repository table.

Developer details

Submit POST /api/v2/prompts with the edited content, metadata fields, and either system_prompt_make_default=on or response_template_make_default=on.
The backend persists the new file, flips the manifest (current_id), returns the saved entry metadata, and redirects with saved=true&default_set=true for telemetry / UI banners.
Existing action=make_default_prompt flows remain supported for manual reverts; the editor path uses the same repository primitive under the hood.

Examples

curl -X POST "https://yourhost/api/v2/prompts" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data-urlencode "system_prompt=You are the nightly assistant." \
    --data-urlencode "system_prompt_label=Night shift baseline" \
    --data "system_prompt_make_default=on"

import os
import requests

base_url = os.getenv("RAG_API_BASE", "https://yourhost/api/v2")
token = os.getenv("RAG_API_TOKEN")

payload = {
    "system_prompt": "You are the nightly assistant.",
    "system_prompt_label": "Night shift baseline",
    "system_prompt_make_default": "on",
}

headers = {
    "Authorization": f"Bearer {token}" if token else None,
    "Content-Type": "application/x-www-form-urlencoded",
}
headers = {k: v for k, v in headers.items() if v}

resp = requests.post(f"{base_url}/prompts", data=payload, headers=headers, allow_redirects=False)
resp.raise_for_status()
print("Redirect query:", resp.headers.get("Location"))

Setting defaults from the repository

Business impact

Reduce hand-offs between prompt authors and operators: any stored system or response template can become the live default with a single click, and the bordered preview preserves whitespace so reviewers can validate content before switching.

Developer details

UI and API share the same primitive: POST /api/v2/prompts with action=make_default_prompt.
Supported types: system, response. Accepts manifest record_id, filename, or blob path in prompt_identifier.
On success the service updates the manifest’s current_id, refreshes caches, and redirects back to /api/v2/prompts with default_set=true (and keeps any existing saved=true flag when combined with editor saves).
Errors (e.g., missing identifier) redirect with error=default_failed.

Examples

curl -X POST "https://yourhost/api/v2/prompts" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    --data "action=make_default_prompt&prompt_type=system&prompt_identifier=system_prompts/autumn_baseline.j2"

import os
import requests

base_url = os.getenv("RAG_API_BASE", "https://yourhost/api/v2")
token = os.getenv("RAG_API_TOKEN")

payload = {
        "action": "make_default_prompt",
        "prompt_type": "response",
        "prompt_identifier": "response_templates/concise_answer.j2",
}

headers = {
        "Authorization": f"Bearer {token}" if token else None,
        "Content-Type": "application/x-www-form-urlencoded",
}
headers = {k: v for k, v in headers.items() if v is not None}

resp = requests.post(f"{base_url}/prompts", data=payload, headers=headers, allow_redirects=False)
resp.raise_for_status()
print("Redirected to", resp.headers.get("Location"))

Parameters

name (string): Prompt name (e.g., system_prompt.j2)
type (string): Prompt type (system, response, experiment)
content (string): Prompt template text
description (string, optional): Description of the prompt
version (string, for revert): Version identifier

Authentication

All endpoints require a valid API key or Azure AD token.

Errors

400 Bad Request: Invalid input
401 Unauthorized: Missing/invalid credentials
404 Not Found: Prompt or version not found
500 Internal Server Error: Prompt operation failed

Usage Tips

Use the UI to preview, edit, and set default prompts.
Use versioning to track changes and revert if needed.
Test prompts before deploying to production.
Hot-reload changes for immediate effect.