Naming & Versioning

Names, slugs, drafts, versions, and tags – the system that runs through everything.

Names, slugs, drafts, and versions work the same way across prompts, workflows, and evaluations. Knowledge bases use naming but not versioning. Once you understand the pattern, it applies everywhere.

Names and slugs

When you create a prompt, workflow, evaluation, or knowledge base, it gets a random name: an adjective and a noun, sometimes amusing, sometimes not. You can rename it any time using the icon next to its name at the top of the editor.

Every name generates a slug automatically: a URL-safe identifier with a type prefix. Prompts get pr_, workflows get wf_, knowledge bases get kb_. The slug is what you use in API calls and workflow references.

When you rename something, the old slug stays as a silent alias. API calls using the previous slug will keep working. No broken integrations, no coordination needed.

Drafts

Every time you save, PromptJuggler creates a new draft revision. Each revision is immutable: you’re not overwriting anything, you’re adding to the history. You can undo, redo, and even save from an earlier revision to branch off in a new direction. It’s not full git, but it’s close.

Drafts are personal. Only you can see and run your drafts. This means you can iterate freely without affecting anyone else in the workspace.

Publishing

When your draft is ready, you publish it. Publishing does three things:

1. Assigns the next version number (v1, v2, v3 …)
2. Lets you attach a note describing what changed
3. Makes this version visible and usable across the entire workspace

Published versions are immutable. You can’t edit v3 after the fact. What you can do is create a new draft from it, improve it, and publish v4.

Tags

Tags are movable labels you attach to published versions. Common examples: production, staging, canary. A tag always points to exactly one version, and you can move it whenever you want.

This lets you decouple “what’s deployed” from “what’s the latest.” Publish v12, test it, then move the production tag from v11 to v12 when you’re confident. If something goes wrong, move it back.

Referencing versions

When calling a prompt or workflow from the API or from a workflow node, you can reference it by:

Reference	What it resolves to
Version number (e.g. 3)	Exactly that version, always
Tag (e.g. production)	Whatever version the tag currently points to
__latest__	The most recently published version

Only published versions can be called from the API. Drafts are for your eyes only.

Publishing workflows

Workflows can contain nodes that reference prompts or other workflows. When you publish a workflow, PromptJuggler checks that every referenced prompt and sub-workflow points to a published version. If any node still references a draft, the publish will fail with a clear error telling you which ones need attention.

This is a safety net: a published workflow should produce the same result every time, and that’s only possible when all its pieces are pinned.

How it applies

Resource	Naming	Slug prefix	Versioning
Prompts	✅	pr_	✅
Workflows	✅	wf_	✅
Evaluations	✅	ev_	✅
Knowledge Bases	✅	kb_	–