Skip to content

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/v1
Auth Authorization: Bearer prm_…
OpenAPI https://prompy-app.vercel.app/api/v1/openapi.json
  1. In Prompy open avatar menu → API keys.
  2. Name the key after where you’ll use it (e.g. my-script) and press Create API key.
  3. 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.

Terminal window
export PROMPY_API_KEY=prm_your_key
# Check the key works
curl 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 } }
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

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.

Terminal window
curl "https://prompy-app.vercel.app/api/v1/prompts?tag=coding&limit=5" \
-H "Authorization: Bearer $PROMPY_API_KEY"
Terminal window
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"
}
}
Terminal window
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.

Send only the fields you want to change. Works on prompts you own.

Terminal window
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"] }'
Terminal window
curl -X DELETE https://prompy-app.vercel.app/api/v1/prompts/PROMPT_ID \
-H "Authorization: Bearer $PROMPY_API_KEY"

Returns 204 No Content.

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.

Terminal window
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.

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 variables
const { 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);
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 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
  • 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.