Developer guide

Use PromptVCS from your application, terminal, and CI pipeline.

Authentication

Generate an API key under Integrations. Pass it as a bearer token. Keys are workspace-scoped and shown once.

Authorization: Bearer pvcs_xxxxxxxxxxxx

Fetch the current prompt

The runtime hot path — fast and edge-cached. Returns the version deployed to the env.

GET /api/v1/prompts/:name/current?env=production

{
  "name": "customer-support-agent",
  "version": "v14",
  "content": "You are a helpful support agent…",
  "model": "claude-sonnet-4-6",
  "environment": "production"
}

Create & deploy versions

POST /api/v1/versions
{ "prompt_name": "customer-support-agent", "content": "…", "note": "tighten refunds" }

POST /api/v1/deploy
{ "prompt_name": "customer-support-agent", "version_tag": "v15", "environment": "production" }

How environments work

Every prompt has three environments — development, staging, and production. Versions (v1, v2, …) are immutable history; an environment is a movable pointer to one version, and each prompt has exactly one live version per environment. Deploying repoints an environment and never touches the others, so you promote by deploying the same version up the chain — and roll back by deploying an older tag.

pvcs deploy customer-support-agent v15 --env staging      # staging → v15 (prod unchanged)
pvcs deploy customer-support-agent v15 --env production   # promote the same version
pvcs deploy customer-support-agent v12 --env production   # roll back

API keys are workspace-scoped, not environment-scoped — pick the environment with the env parameter at request time. Derive it from your host once so each deployment reads the right prompt with the same key:

const env =
  process.env.VERCEL_ENV === "production" ? "production"
  : process.env.VERCEL_ENV === "preview" ? "staging"
  : "development";

GET /api/v1/prompts/:name/current?env=${env}

On the Free plan only production is available; paid plans unlock staging and development.

CLI

export PROMPTVCS_API_KEY=pvcs_…
export PROMPTVCS_API_URL=https://your-app.vercel.app

pvcs pull customer-support-agent --env production
pvcs push customer-support-agent -f prompt.txt -n "tighten refunds"
pvcs deploy customer-support-agent v15 --env production
pvcs eval customer-support-agent --env staging

CI eval gate (GitHub Action)

Run your eval suite on every pull request and fail the check when quality drops.

- uses: promptvcs/eval-action@v1
  with:
    api_key: ${{ secrets.PROMPTVCS_API_KEY }}
    prompt: customer-support-agent
    environment: staging
    llm_api_key: ${{ secrets.OPENAI_API_KEY }}
    fail_threshold: '0.85'

Rate limits & errors

Public endpoints are rate-limited per key and return consistent JSON errors with standard HTTP status codes (401, 402, 404, 422,429).