Skip to content
PromptCache
Get started

Developers

Versions & forking

Publish snapshots, version history, and fork prompts

API base URL

https://api.promptcache.app

Mental model

Draft content lives on the prompt document. Saving updates the draft only, no version row is created.

Published snapshots are separate version records created only when you call POST /api/v1/prompts/:id/publish. Each publish captures the current draft, assigns the next version number, and keeps that snapshot immutable.

After publishing you can keep editing the draft. The next publish adds another snapshot without overwriting older ones.

Who can publish?

Publish (and fork from a private prompt) require a signed-in user session (JWT from POST /api/v1/auth/login), not an API key alone. API keys are ideal for automation against prompts (list, get, invoke, inject, create/update/delete where permitted), but publishing and forking are gated to interactive user credentials.

List versions

Code
GET /api/v1/prompts/:id/versions?published=true
  • Omit published or set it to something other than true to list all versions for the prompt (newest-first by version number).
  • published=true returns only published snapshots, sorted with the newest publication first, suitable for a timeline UI.

Typical fields include version, status, publishedAt, template, variables, and populated createdBy.

Get one version

Code
GET /api/v1/prompts/:id/versions/:versionId

Returns a single version document if it belongs to that prompt and you have org access. Use this for read-only previews (“what did we ship in v3?”) without mutating the draft.

Publish

Code
POST /api/v1/prompts/:id/publish
Content-Type: application/json
 
{ "changeLog": "Optional note (max 280 chars)" }

Snapshots the current draft into a new published PromptVersion. Requires user authentication.

Save and publish (bulk-friendly, uses server-side draft, no client payload):

Code
POST /api/v1/prompts/:id/save-and-publish

Invoke uses published snapshots

POST /api/v1/prompts/:id/invoke resolves published content by default (currentVersionId), not the live draft. Unpublished prompts return 400 with code NO_PUBLISHED_VERSION.

Optional pinning:

  • ?version=N or body { "version": N }
  • ?env=preview or ?env=production (see environments below)

The response may include header X-PromptCache-Version. Use POST …/inject for draft preview only.

Restore draft from a version

Code
POST /api/v1/prompts/:id/versions/:versionId/restore

Copies the snapshot’s template and variables onto the prompt draft. Does not change version history or currentVersionId.

Compare versions

Code
GET /api/v1/prompts/:id/versions/diff?from=<versionId|draft>&to=<versionId|draft>

Returns line-level template hunks and variable add/remove/change metadata.

Environments

Code
GET /api/v1/prompts/:id/environments
POST /api/v1/prompts/:id/environments/:env/promote
Content-Type: application/json
 
{ "versionId": "<published PromptVersion _id>" }

:env is preview or production. Invoke with ?env=production uses the pinned snapshot when set.

Unpublish from the public gallery

Code
DELETE /api/v1/prompts/:id/publish

Clears public visibility for the prompt (and related public index entries). This does not delete PromptVersion history; it affects whether the prompt appears in the public catalog.

Fork from a published version

Forking creates a brand new Prompt in a target organization, copying template and variables from a published snapshot. The source prompt is unchanged.

Code
POST /api/v1/prompts/:id/versions/:versionId/fork
Content-Type: application/json
 
{
  "targetOrganizationId": "YOUR_ORG_ID",
  "name": "Email Responder (fork)"
}

Requirements

  • User authentication (JWT), not API-key-only.
  • name is required and must be non-empty after trimming.
  • targetOrganizationId may be omitted: the server defaults to the caller’s current organization from context.
  • You must have ACTIVE membership in the target organization (the org that will own the new prompt).
  • Only PUBLISHED versions can be forked; draft snapshots cannot.

Behavior

  • The new prompt is created with v1 already published from the forked snapshot (versionCount: 1).
  • forkedFromVersionId references the source PromptVersion’s id for lineage.
  • Tags are reset (empty); description is copied from the source prompt when available.
  • The fork is private (isPublic: false) by default.

Example response

Code
{
  "prompt": {
    "_id": "…",
    "name": "Email Responder (fork)",
    "slug": "email-responder-fork",
    "forkedFromVersionId": "<sourceVersionId>",
    "isPublic": false
  }
}

Fork vs copy-paste

Forking is the supported way to clone a known published revision into another workspace with correct attribution (forkedFromVersionId). Copying text manually loses that link and may drift from the versioned template shape.

Public prompts

To fork from the public catalog (last published snapshot of a public prompt), use POST /api/v1/public/prompts/:id/fork with organizationId and name in the body, also user session required. See Public API.

Dashboard: Versions tab

The dashboard shows a published timeline for each prompt: version number, changelog, author, time, and actions to view, compare to draft, restore to draft, fork, or promote to preview/production environments.

Org Settings → Webhooks can subscribe to version.published events (signed X-PromptCache-Signature POST delivery).