REST API
Prompy has a small JSON REST API next to the MCP server. Both use the same API key.
Base URL https://prompy-app.vercel.app/api/v1Auth Authorization: Bearer prm_…OpenAPI https://prompy-app.vercel.app/api/v1/openapi.jsonGet an API key
Section titled “Get an API key”- In Prompy open avatar menu → API keys.
- Name the key after where you’ll use it (e.g. my-script) and press Create API key.
- Copy it right away. It starts with
prm_and is shown only once. Prompy stores only a SHA-256 hash.
Revoke a key from the same page at any time. Each key shows when it was last used.
Quick start
Section titled “Quick start”export PROMPY_API_KEY=prm_your_key
# Check the key workscurl https://prompy-app.vercel.app/api/v1/me \ -H "Authorization: Bearer $PROMPY_API_KEY"{ "data": { "id": "0e89…", "username": "ada", "full_name": "Ada", "avatar_url": null, "prompt_count": 12, "public_count": 3 } }Endpoints
Section titled “Endpoints”| Method | Path | What it does |
|---|---|---|
GET |
/me |
The account that owns this key |
GET |
/prompts |
Search prompts you can access |
POST |
/prompts |
Create a prompt |
GET |
/prompts/{id} |
Read one prompt |
PATCH |
/prompts/{id} |
Update a prompt you own |
DELETE |
/prompts/{id} |
Delete a prompt you own |
GET |
/tags |
Your tags with usage counts |
GET |
/templates |
Published design templates |
GET |
/templates/{slug} |
One design template with its prompt |
Search prompts
Section titled “Search prompts”GET /prompts?q=&tag=&include_public=false&limit=20
| Query | Description |
|---|---|
q |
Text to find in title, note or prompt text |
tag |
Only prompts with this tag |
include_public |
true to also search other users’ public prompts |
limit |
1–100, default 20 |
Results include your own prompts and your workspaces’ prompts. The list doesn’t include the full prompt text; call GET /prompts/{id} for that.
curl "https://prompy-app.vercel.app/api/v1/prompts?tag=coding&limit=5" \ -H "Authorization: Bearer $PROMPY_API_KEY"Read a prompt
Section titled “Read a prompt”curl https://prompy-app.vercel.app/api/v1/prompts/46d42443-44c9-4c91-9c9c-ee8adc55164b \ -H "Authorization: Bearer $PROMPY_API_KEY"{ "data": { "id": "46d42443-…", "title": "Explain code like a patient mentor", "description": "Good for onboarding juniors", "content": "Explain the following code step by step…\n\n{{code}}", "tags": ["coding", "mentoring"], "visibility": "public", "author": "ada", "updated_at": "2026-11-10T10:42:11Z" }}Create a prompt
Section titled “Create a prompt”curl -X POST https://prompy-app.vercel.app/api/v1/prompts \ -H "Authorization: Bearer $PROMPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "title": "Summarise in 3 bullets", "content": "Summarise this in 3 bullets:\n\n{{text}}", "tags": ["writing"], "visibility": "private" }'Returns 201 with the new prompt. visibility defaults to private.
Update a prompt
Section titled “Update a prompt”Send only the fields you want to change. Works on prompts you own.
curl -X PATCH https://prompy-app.vercel.app/api/v1/prompts/PROMPT_ID \ -H "Authorization: Bearer $PROMPY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "visibility": "public", "tags": ["writing", "summary"] }'Delete a prompt
Section titled “Delete a prompt”curl -X DELETE https://prompy-app.vercel.app/api/v1/prompts/PROMPT_ID \ -H "Authorization: Bearer $PROMPY_API_KEY"Returns 204 No Content.
Design templates
Section titled “Design templates”GET /templates?q=&style=&limit=20 lists published design templates in gallery order: slug, title, description, category, style_tags, palette, copy_count, and full links in url, cover_url and demo_url. limit is 1–50.
GET /templates/{slug} adds the full prompt, the names of its variables (its {{placeholders}}, in order) and the screenshots (desktop, mobile, dark). Add ?copy=true when you are about to use the prompt so it counts as a copy.
curl "https://prompy-app.vercel.app/api/v1/templates/minimal-saas?copy=true" \ -H "Authorization: Bearer $PROMPY_API_KEY"Replace each {{name}} in prompt with your value before pasting it into an AI coding tool. While the design_templates flag is off, both endpoints return 404 with the code not_available.
JavaScript / TypeScript
Section titled “JavaScript / TypeScript”const BASE = "https://prompy-app.vercel.app/api/v1";const headers = { Authorization: `Bearer ${process.env.PROMPY_API_KEY}`, "Content-Type": "application/json",};
// Find a prompt and fill its variablesconst { data: found } = await fetch(`${BASE}/prompts?q=summarise`, { headers }).then((r) => r.json());const { data: prompt } = await fetch(`${BASE}/prompts/${found[0].id}`, { headers }).then((r) => r.json());const filled = prompt.content.replace("{{text}}", article);Python
Section titled “Python”import os, requests
BASE = "https://prompy-app.vercel.app/api/v1"H = {"Authorization": f"Bearer {os.environ['PROMPY_API_KEY']}"}
prompts = requests.get(f"{BASE}/prompts", params={"tag": "coding"}, headers=H).json()["data"]for p in prompts: print(p["id"], p["title"])Errors
Section titled “Errors”Errors use HTTP status codes and a JSON body:
{ "error": { "code": "invalid_token", "message": "API key is invalid or revoked." } }| Status | code |
Meaning |
|---|---|---|
400 |
invalid_json |
Body isn’t valid JSON |
401 |
unauthorized |
Missing or malformed Authorization header |
401 |
invalid_token |
Key is wrong or was revoked |
404 |
not_found |
Prompt doesn’t exist or you can’t access it |
422 |
invalid_input |
A field is missing or out of range |
Security model
Section titled “Security model”- Keys are random 192-bit values; only their SHA-256 hash is stored.
- Every request is checked inside the database before any data is read or written. The API can never return another user’s private prompts.
- Keys can read your own prompts, your workspaces’ prompts and public prompts. They can create prompts, and update or delete only prompts you own.
- CORS is open so you can call the API from any origin, but keep the key on a server.