Core Concepts

Understanding the building blocks of PromptOps.

Projects

A Project is the top-level container in PromptOps — think of it as a workspace or organization. Everything belongs to a project: prompts, versions, deployments, and API keys.

Typically, you'll have one project per application or team. Projects are created via the API or dashboard and return an initial API key.

Prompts

A Prompt represents a single AI behavior you want to manage — for example, "onboarding-email" or "support-classifier". Each prompt has:

  • Slug — A unique, URL-safe identifier (e.g., onboarding-email). This is what your SDK uses to fetch the prompt.
  • Name — A human-readable display name.
  • Description — Optional context about what this prompt does.

Prompts don't contain the actual content — that lives in versions.

Versions

A Version is an immutable snapshot of a prompt's content and configuration. Every time you change a prompt, you create a new version. Versions contain:

  • System Prompt — The system-level instruction (e.g., "You are a helpful assistant...")
  • User Template — The user message template with {{variable}} placeholders
  • Model — The target LLM model (e.g., gpt-4, claude-3-sonnet)
  • Temperature — The creativity/randomness setting (0.0 – 2.0)
  • Max Tokens — Optional output length limit
  • Metadata — Arbitrary JSON for custom data

Versions are numbered automatically (v1, v2, v3...) and are immutable once created. To change a prompt, you create a new version.

Environments

PromptOps supports three environments, mirroring standard deployment pipelines:

  • dev — For development and testing. New versions auto-deploy here.
  • staging — For pre-production validation.
  • production — The live environment serving end users.

Each environment independently tracks which version is active. This lets you test v5 indev while production safely runs v3.

Deployments

A Deployment is the link between a prompt version and an environment. It records:

  • Which version is active in which environment
  • When it was promoted
  • Who promoted it

The typical flow is: Create version → Auto-deploys to dev → Promote to staging → Promote to production.

You can also rollback any environment to its previous version with a single API call.

API Keys

API Keys authenticate requests to the PromptOps API. Each key:

  • Is scoped to a single project
  • Is scoped to a single environment (dev, staging, or production)
  • Has a visible prefix (e.g., po_live_abc1) for identification
  • Is hashed with bcrypt — we never store the raw key
  • Can be revoked at any time

The full API key is only shown once — at creation time. After that, only the prefix is visible.

SDK Caching

The TypeScript SDK includes an in-memory cache with two key behaviors:

  • TTL (Time-To-Live) — Cached prompts expire after a configurable duration (default: 60 seconds). During this window, getPrompt() returns instantly without an API call.
  • Stale Fallback — If the API is unreachable and the cache has expired, the SDK serves the last-known-good value rather than throwing an error. This ensures your application keeps working even if PromptOps is temporarily down.

How It All Fits Together

┌─────────────┐
│   Project    │ ← Your app / team
├─────────────┤
│  API Keys    │ ← Scoped per environment
├─────────────┤
│   Prompts    │ ← Identified by slug
│  ┌─────────┐ │
│  │Versions │ │ ← Immutable snapshots (v1, v2, v3...)
│  └─────────┘ │
│  ┌─────────┐ │
│  │Deploys  │ │ ← version ↔ environment mapping
│  └─────────┘ │
└─────────────┘

SDK call: getPrompt("slug") → resolves active version for environment