openpromptstore

Documentation

Versioned prompt management for production LLM apps

Open Prompt Store is a lightweight hosted or self-hostable registry for prompts. Name prompts, save immutable versions, move aliases like @prod, and fetch the exact text your application needs without shipping a new deploy.

Get StartedAPI Reference

Why Open Prompt Store

Prompt changes should be reviewable, reversible, and observable without coupling every wording tweak to an application deploy. Open Prompt Store keeps the registry small and explicit so teams can manage production prompt text with the same care they use for code.

Getting started

Create an organization, mint an API key, and choose the integration path that matches your app. Runtime clients authenticate with Authorization: Bearer keys, while the web UI and CLI cover day-to-day prompt operations.

Python SDK

Install openpromptstore, fetch prompt templates, and render them with strict variables.

Read guide

TypeScript SDK

Use @openpromptstore/sdk in your app with the same rendering semantics and TTL cache.

Read guide

CLI

Create prompts, push versions, move aliases, compare changes, and render from a shell.

Read guide

Hosted Service

Use the official hosted service when you want the same versioned prompt API without operating the app server, database, deploys, backups, or scaling yourself. The hosted and self-hosted paths share the same API shape and SDK semantics.

Core concepts

The model is intentionally small: prompts are named records, versions are immutable snapshots, aliases are movable pointers, and variables are rendered by SDKs with shared semantics.

Immutable versions

Every save creates a numbered version such as welcome@1, welcome@2, and welcome@3.

Mutable aliases

Move @prod or @staging atomically to promote a prompt or recover without a deploy.

Template variables

Declare {{user_name}} in prompt bodies and render with strict missing-variable checks.

prompt reference
welcome@latest
welcome@prod
welcome@staging
welcome@3

{{user_name}}, welcome to {{product}}.

API Keys

Runtime clients use bearer keys scoped to an organization and project context. Keep user login in WorkOS AuthKit, and use API keys for SDKs, CLIs, and server-to-server prompt fetching.

curl http://localhost:8000/v1/prompts \
  -H "Authorization: Bearer $OPENPROMPTSTORE_API_KEY" \
  -H "x-organization-id: $OPS_ORGANIZATION_ID" \
  -H "x-project-id: $OPS_PROJECT_ID"

Install

Add the runtime SDK for your application language. The Python package also includes the openpromptstore CLI.

Python

uv add openpromptstore

TypeScript

npm install @openpromptstore/sdk

Python SDK

from openpromptstore import PromptStore

store = PromptStore(
  "http://localhost:8000",
  api_key="your_api_key",
  organization_id="...",
  project_id="..."
)

text = store.render("welcome@prod", {
  "user_name": "Ada",
  "product": "Acme",
})

TypeScript SDK

import { PromptStore } from "@openpromptstore/sdk";

const store = new PromptStore({
  baseUrl: "http://localhost:8000",
  apiKey: process.env.OPS_API_KEY,
  organizationId: process.env.OPS_ORGANIZATION_ID,
  projectId: process.env.OPS_PROJECT_ID,
});

const text = await store.render("welcome@prod", {
  user_name: "Ada",
  product: "Acme",
});

HTTP API

The public API is the shared backend for the web app, CLI, and SDKs. Organizations own users and runtime keys; projects create separate prompt namespaces inside each organization.

A machine-readable OpenAPI document is available at /openapi.json.

GET/v1/healthCheck service health.
GET/v1/organizationsList organizations for the signed-in user.
POST/v1/organizationsCreate a WorkOS-backed organization and default project.
GET/v1/projectsList projects in an organization.
POST/v1/projectsCreate a project inside an organization.
PATCH/v1/projectsRename a project.
GET/v1/promptsList prompts in the active project.
POST/v1/prompts/:name/versionsPush a new immutable prompt version.
POST/v1/prompts/:name/aliasesPoint an alias at a version.
POST/v1/prompts/:ref/renderRender a prompt reference with variables.
POST/v1/api-keysCreate a WorkOS-managed runtime key.

Rollbacks

Move @prod back to a known-good version in seconds.

Environments

Use aliases like @dev, @staging, and @prod for deploy targets.

Template Caching

Cache rendered templates with SDK TTLs and explicit invalidation by version reference.

Authentication

Use WorkOS AuthKit for signup, login, MFA, and invitations.

Deploying

Run one Next.js container backed by Postgres or deploy the hosted stack.

Self-hosting quickstart

git clone https://github.com/uhryvacheuski/openpromptstore
cd openpromptstore
npm install
npm run db:migrate
npm run dev

CLI workflow

The Python package ships a CLI for local prompt operations, version pushes, alias management, and render checks.

openpromptstore login
openpromptstore project list
openpromptstore create welcome --description "System prompt for onboarding"
openpromptstore push welcome ./prompts/welcome.md --message "Initial version"
openpromptstore alias set welcome prod 1
openpromptstore render welcome@prod --var user_name=Ada --var product=Acme