Docs Prompts Storage

Prompts Storage

Prompts Storage is Mockarty’s managed home for AI prompt templates. Each prompt is identified by a UUID, carries a body, an optional target model, tags, and — critically — a FIFO-20 version history with one-call rollback.

AI buttons in the UI, Test Case Management (TCM) steps, and agent tasks reference prompts by ID rather than copying their text. Editing a prompt propagates to every consumer without code changes.

Table of Contents

  1. Why managed prompts?
  2. Versioning model
  3. Attach to AI buttons and TCM steps
  4. SDK and CLI examples

Why managed prompts?

Prompt engineering is iterative. A team that ships an AI-assisted feature typically tweaks the prompt dozens of times in the first month. Without a store, every tweak means editing scattered templates and redeploying.

With Prompts Storage:

  • One source of truth — every consumer references the same prompt ID.
  • Safe iteration — every save creates a new version; you can diff, compare, and roll back without losing work.
  • Auditable — each version records the author and timestamp.
  • Portable — prompts export cleanly for air-gapped deployments.

Versioning model

  • The first POST /api/v1/stores/prompts creates version 1.
  • Every subsequent PUT that changes the body field creates a new version.
  • History is FIFO-capped at 20: when the 21st edit lands, the oldest historical version is dropped. The current version is always accessible via the top-level GET.
  • Rollback (POST /.../rollback?to=N) restores the body from version N. The current body is itself pushed onto the history stack first — so rolling back never destroys your latest draft.

Placeholder syntax

Prompt bodies support double-curly placeholders that the server parses out
on save and that consumers (AI buttons, agent chat, API tester
environments) fill in at use-time.

  • Form: two opening curly braces, the placeholder name, two closing
    curly braces — for example Hello, {{username}}, generate a summary of {{report_id}}.
  • Allowed characters: letters, digits, _. Names are case-sensitive
    but conventionally lowercase. Write the braces unspaced — {{username}}.
    Whitespace inside the braces ({{ username }}) is not recognised as a
    placeholder.
  • Parsed keys: the create / update endpoints return a parsedKeys
    array of every unique placeholder seen in the body. The AI button
    picker uses this list to render a structured form before invocation.
  • Missing values: a variable declared required with no default and
    no supplied value makes rendering fail. Any other placeholder left unfilled
    renders as an empty string (it is not emitted half-filled with <no value>).

Attach to AI buttons and TCM steps

AI-powered UI buttons (e.g. “Summarise failures”, “Explain this mock”) accept a promptId. The Mockarty agent loads the current version at invocation time; rolling back the prompt immediately changes button behaviour.

TCM steps reference prompts in the same way: a test step of type ai-assisted carries a promptId rather than an inline template.

SDK and CLI examples

CLI

mockarty-cli prompts create \
  --name tcm-step-summarizer \
  --body "Summarize the following test step in one sentence: {{.step}}" \
  --model claude-opus-4-7 \
  --tag tcm --tag summary

mockarty-cli prompts update "$PROMPT_ID" --body "Summarize in ≤15 words: {{.step}}"
mockarty-cli prompts versions list "$PROMPT_ID"
mockarty-cli prompts versions rollback "$PROMPT_ID" 1

Go SDK

p, _ := client.Prompts().CreatePrompt(ctx, mockarty.Prompt{
    Name:  "tcm-step-summarizer",
    Body:  "Summarize the following test step in one sentence: {{.step}}",
    Model: "claude-opus-4-7",
    Tags:  []string{"tcm", "summary"},
})
_, _ = client.Prompts().UpdatePrompt(ctx, p.ID, mockarty.Prompt{Body: "Summarize in ≤15 words: {{.step}}"})
versions, _ := client.Prompts().ListVersions(ctx, p.ID)
_ = versions
_, _ = client.Prompts().Rollback(ctx, p.ID, 1)

Python SDK

p = client.prompts.create(
    name="tcm-step-summarizer",
    body="Summarize the following test step in one sentence: {{.step}}",
    model="claude-opus-4-7",
    tags=["tcm", "summary"],
)
client.prompts.update(p["id"], body="Summarize in ≤15 words: {{.step}}")
versions = client.prompts.list_versions(p["id"])
client.prompts.rollback(p["id"], to_version=1)

Java SDK

Map<String, Object> p = client.prompts().create(
    "tcm-step-summarizer",
    "Summarize the following test step in one sentence: {{.step}}",
    Map.of("model", "claude-opus-4-7", "tags", List.of("tcm", "summary")));
client.prompts().update((String) p.get("id"),
    Map.of("body", "Summarize in ≤15 words: {{.step}}"));
List<Map<String, Object>> versions = client.prompts().listVersions((String) p.get("id"));
client.prompts().rollback((String) p.get("id"), 1);

See also: AI Features, Secrets Storage.

Previous
LLM API Mocks