API versions

The version is in the path. A version never changes shape once published: fields may be added, never removed or renamed, and behaviour never changes underneath you. Anything breaking lands in a new version with its own docs.

Version	Status	Surface	Docs
v2	current	Read, write, publish, list; MCP server at `/api/v2/mcp`	REST API v2, MCP
v1	frozen	`GET /api/v1/prompts/:id` only	REST API v1

Every response carries an X-API-Version header. v1 responses also carry Deprecation: true. v1 has no removal date; if one is ever set it will be announced here and to the email on the account well ahead of time.

What changed in v2

Query parameters on GET. ?version=latest reads the newest saved version (for staging), ?version=<hash> pins one, ?guard=false returns the prompt without Prompt Guard. v1 ignores these and always serves production with the guard on.
New response fields. name, description, variables, label and production_version. version is the hash of the version actually served.
Write endpoints. List, create, save a version and publish. v1 is read-only.
MCP server at /api/v2/mcp.
Hardening. Strict request validation (unknown fields are rejected), a 1 MB body limit, throttling of failed authentication per client, and Cache-Control: no-store on every response.

Moving from v1 to v2

For a read-only integration the change is the path. The response is a superset of v1, so existing parsing keeps working.

# before
curl https://superprompts.app/api/v1/prompts/<PROMPT_ID> -H "x-api-key: <API_KEY>"

# after
curl https://superprompts.app/api/v2/prompts/<PROMPT_ID> -H "x-api-key: <API_KEY>"

The superprompts npm package 0.2.0 and the Python package 0.1.0 already call v2. npm versions 0.0.x call v1 and keep working.