API Reference

The PromptVault HTTP API - read prompts and version history directly over REST. This is the same API the SDK calls under the hood.

The PromptVault HTTP API lets you read prompts and their version history directly over REST. The @promptv/sdk is a thin client over these same endpoints - reach for the raw API when you work in a language the SDK doesn't cover, or when you need full control over the request.

Base URL

https://app.promptvlt.com

All endpoints are versioned under /api/v1.

Authentication

Every request must send an API key as a bearer token:

Authorization: Bearer pv_live_xxxxxxxxxxxxxxxxxxxx

Create keys in the dashboard under Settings → API keys (see Settings and API keys). The key prefix decides which version a read resolves to:

Key prefix	Reads resolve to
`pv_live_`	The prompt's live version.
`pv_test_`	The prompt's staging version, falling back to live when no staging version is set.

Keys are workspace-scoped and grant read access to every prompt in that workspace. Treat them like secrets - store them in environment variables, never in client-side code.

Endpoints

Method	Path	Purpose
`GET`	`/api/v1/prompts`	List every prompt in the workspace.
`GET`	`/api/v1/prompts/{slug}`	Read the resolved (live or staging) version of one prompt.
`GET`	`/api/v1/prompts/{slug}/versions`	List the full version history of a prompt.
`GET`	`/api/v1/prompts/{slug}/versions/{label}`	Read one specific version by label.

Response headers

The list endpoint returns the workspace's billing state in a response header so you can surface plan limits without a second call:

x-promptvault-plan-status: active

Errors

Errors return a non-2xx status with a JSON body:

{ "error": "Prompt not found" }

Status	Meaning
`401`	Missing, malformed, or invalid API key.
`404`	The prompt or version does not exist in this workspace.
`429`	The workspace has exceeded its plan's read limit.

Metering

Each successful prompt read is metered against the workspace plan. Listing prompts and listing versions are management calls and are billed differently from per-prompt reads - see your plan for details.