API Reference

GET /api/prompts/retrieve

Retrieve a prompt version by slugs. By default, PromptStash returns the latest version tagged active, or you can request an exact prompt version number with x-version.

Method: GET
URL: https://promptstash.app/api/prompts/retrieve
Runtime: Edge

Headers

x-api-key (required): Your PromptStash API key
x-project-slug (required): Project slug
x-prompt-slug (required): Prompt slug
x-tag (optional): Version tag, defaults to active
x-version (optional): Exact prompt version number, such as 1 or 3

x-tag and x-version are mutually exclusive.

Responses

200 OK


{
  "content": "...prompt content...",
  "name": "Version name",
  "version": 3,
  "tags": ["active"],
  "variables": [
    {
      "name": "tone",
      "type": "string",
      "required": true,
      "requireUserInput": true
    }
  ],
  "schema": {
    "type": "object",
    "properties": {
      "tone": { "type": "string" }
    },
    "required": ["tone"]
  }
}

400 Bad Request


{ "ok": false, "error": "Missing required headers" }


{ "ok": false, "error": "x-version and x-tag cannot be used together" }


{ "ok": false, "error": "Invalid x-version header" }

401 Unauthorized


{ "ok": false, "error": "Invalid API key" }

404 Not Found


{ "ok": false, "error": "Prompt not found or has no matching versions" }

Examples

Retrieve the latest active version:


curl -X GET \
  'https://promptstash.app/api/prompts/retrieve' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-project-slug: your-project' \
  -H 'x-prompt-slug: your-prompt' \
  -H 'x-tag: active'

Retrieve an exact version number:


const res = await fetch("https://promptstash.app/api/prompts/retrieve", {
  headers: {
    "x-api-key": process.env.PROMPTSTASH_API_KEY!,
    "x-project-slug": "your-project",
    "x-prompt-slug": "your-prompt",
    "x-version": "3",
  },
});
if (!res.ok) throw new Error(await res.text());
const data = await res.json();

GET /api/prompts/variables

Retrieve only the prompt variables that require user input. Version selection works the same way as /api/prompts/retrieve.

Method: GET
URL: https://promptstash.app/api/prompts/variables
Runtime: Edge

Headers

x-api-key (required): Your PromptStash API key
x-project-slug (required): Project slug
x-prompt-slug (required): Prompt slug
x-tag (optional): Version tag, defaults to active
x-version (optional): Exact prompt version number, such as 1 or 3

x-tag and x-version are mutually exclusive.

Responses

200 OK


{
  "variables": [
    {
      "name": "tone",
      "type": "string",
      "required": true,
      "requireUserInput": true
    }
  ],
  "schema": {
    "type": "object",
    "properties": {
      "tone": { "type": "string" }
    },
    "required": ["tone"]
  }
}

400 Bad Request


{ "ok": false, "error": "Missing required headers" }


{ "ok": false, "error": "x-version and x-tag cannot be used together" }


{ "ok": false, "error": "Invalid x-version header" }

401 Unauthorized


{ "ok": false, "error": "Invalid API key" }

404 Not Found


{ "ok": false, "error": "Prompt not found or has no matching versions" }

Example


curl -X GET \
  'https://promptstash.app/api/prompts/variables' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'x-project-slug: your-project' \
  -H 'x-prompt-slug: your-prompt' \
  -H 'x-version: 3'