📖 API Documentation

PromptShelf REST API provides complete prompt management, execution, and evaluation capabilities. All endpoints return JSON.

🌐 Base URL

https://promptshelf.ai/api

📄 Format

JSON

⏱️ Rate Limit

100 req/min

Quick Test

Get All Promptscurl

curl -s https://promptshelf.ai/api/prompts | jq '.prompts | length'
# => 4 (sample data)

🔑 Authentication

The API is currently open access (development phase). Production will use Bearer Token authentication.

POST/api/auth

User login, register, or get current user info

Parameter	Type	Required	Description
action	string	Yes	"login" \| "register" \| "me"
email	string	Yes	User email (required for login/register)
name	string	No	User name (Required for register)
sessionToken	string	No	Session token (Used for me action)

Registercurl

curl -X POST https://promptshelf.ai/api/auth \
  -H "Content-Type: application/json" \
  -d '{
    "action": "register",
    "email": "dev@example.com",
    "name": "Developer"
  }'

Responsejson

{
  "user": {
    "id": "u1716825600000",
    "email": "dev@example.com",
    "name": "Developer",
    "plan": "starter",
    "createdAt": "2026-05-27"
  },
  "sessionToken": "sess_a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

📋 Prompts

GET/api/prompts

Get all prompts list, supports category filtering

Parameter	Type	Required	Description
category	string	No	Filter by category ("all" returns all)
id	string	No	Get a single prompt by ID

Requestcurl

curl https://promptshelf.ai/api/prompts?category=Developer Tools

Responsejson

{
  "prompts": [
    {
      "id": "p2",
      "name": "Code Review Assistant",
      "description": "Multi-dimensional code review...",
      "category": "Developer Tools",
      "tags": ["Code Review", "Security", "Performance"],
      "model": "deepseek-v4",
      "currentVersion": 2,
      "versions": [...],
      "totalRuns": 5000,
      "totalCostUsd": 89.5,
      "avgQualityScore": 91
    }
  ],
  "total": 2
}

POST/api/prompts

Create a new prompt

Parameter	Type	Required	Description
name	string	Yes	Prompt name (max 200 chars)
content	string	Yes	Prompt content (max 50000 chars)
description	string	No	Description
category	string	No	Category (default: "Uncategorized")
tags	string[]	No	Tags array (max 20)
model	string	No	Default model (default: "deepseek-v4")
systemPrompt	string	No	System prompt
variables	object	No	Variable definitions {"key": "default_value"}

Createcurl

curl -X POST https://promptshelf.ai/api/prompts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Email Classifier",
    "description": "Auto-classify customer emails",
    "category": "Business Automation",
    "tags": ["Email", "Classification"],
    "content": "Classify the following email: complaint/inquiry/suggestion/gratitude\n\nEmail: {{email}}\n\nOutput in JSON format",
    "variables": {"email": ""}
  }'

PUT/api/prompts

Update prompt (only whitelisted fields allowed)

Parameter	Type	Required	Description
id	string	Yes	Prompt ID
name	string	No	New name
description	string	No	New description
category	string	No	New category
tags	string[]	No	New tags
model	string	No	New default model
isPublic	boolean	No	<span className="text-red-400">Yes</span><span className="text-gray-600">No</span>公开

Updatecurl

curl -X PUT https://promptshelf.ai/api/prompts \
  -H "Content-Type: application/json" \
  -d '{"id": "p1", "name": "Email Classifier v2", "isPublic": true}'

DELETE/api/prompts

Delete Prompt

Parameter	Type	Required	Description
id	string	Yes	Prompt ID (query parameter)

Deletecurl

curl -X DELETE "https://promptshelf.ai/api/prompts?id=p1"

▶️ Execute Prompt

Execute a prompt and get LLM output. Auto-substitutes variables, records run history, and calculates cost and quality score.

POST/api/execute

Execute prompt (real LLM API call)

Parameter	Type	Required	Description
promptId	string	Yes	Prompt ID to execute
variables	object	No	Variable values {"email": "user input..."}
model	string	No	Override default model

Executecurl

curl -X POST https://promptshelf.ai/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "promptId": "p1",
    "variables": {
      "email": "Your product is terrible! Refund!"
    }
  }'

Responsejson

{
  "output": "{\"category\": \"complaint\", \"confidence\": 0.98, ...}",
  "model": "deepseek-v4",
  "provider": "deepseek",
  "latencyMs": 920,
  "inputTokens": 156,
  "outputTokens": 48,
  "costUsd": 0.000035,
  "qualityScore": 100,
  "finishReason": "stop"
}

✅ Batch Evaluate

Evaluate prompt quality with multiple test cases. Supports auto-scoring and pass rate statistics.

POST/api/evaluate

Batch Evaluate Prompt（最多 100 个Test cases）

Parameter	Type	Required	Description
prompt	string	Yes	Prompt content (supports {{variable}} templates)
systemPrompt	string	No	System prompt
model	string	No	Evaluation model (default: deepseek-v4)
testCases	array	Yes	Test cases array (max 100)

Evaluatecurl

curl -X POST https://promptshelf.ai/api/evaluate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Classify the following email: {{email}}",
    "testCases": [
      {"id": "t1", "name": "Complaint test", "inputs": {"email": "Refund!"}, "expectedOutput": "complaint", "rubric": "Must classify as为投诉"},
      {"id": "t2", "name": "Inquiry test", "inputs": {"email": "多少钱？"}, "expectedOutput": "inquiry", "rubric": "Must classify as为咨询"}
    ]
  }'

Responsejson

{
  "results": [
    {"testCaseId": "t1", "name": "Complaint test", "passed": true, "qualityScore": 95, "latencyMs": 850},
    {"testCaseId": "t2", "name": "Inquiry test", "passed": true, "qualityScore": 95, "latencyMs": 920}
  ],
  "summary": {
    "totalTests": 2,
    "passedTests": 2,
    "passRate": 1.0,
    "avgLatencyMs": 885,
    "avgQualityScore": 95,
    "totalCostUsd": 0.000069
  }
}

💬 Chat API

Universal chat interface supporting DeepSeek, OpenAI, and Anthropic multi-model switching. Used by Playground and custom apps.

POST/api/chat

Send chat message (multi-model support)

Parameter	Type	Required	Description
model	string	Yes	Model ID (deepseek-v4 / gpt-4o / claude-sonnet-4 等）
messages	array	Yes	Message array [{role, content}]
temperature	number	No	Temperature (default 0.7)
max_tokens	number	No	Max tokens (default 2048)

Requestcurl

curl -X POST https://promptshelf.ai/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4",
    "messages": [
      {"role": "system", "content": "You are <span className="text-red-400">Yes</span>an assistant"},
      {"role": "user", "content": "Hello"}
    ]
  }'

📊 Run History

GET/api/runs

Get run history

Parameter	Type	Required	Description
promptId	string	No	Filter by prompt ID
limit	number	No	Limit (default 50, max 500)
stats	string	No	"true" to return statistics

Get statscurl

curl "https://promptshelf.ai/api/runs?stats=true"

Responsejson

{
  "totalRuns": 23700,
  "totalCost": 256.82,
  "avgLatency": 950,
  "avgQuality": 88.5,
  "passRate": 0.92,
  "byModel": {
    "deepseek-v4": {"runs": 18000, "cost": 45.2, "avgLatency": 920},
    "gpt-4o": {"runs": 5700, "cost": 211.6, "avgLatency": 1500}
  },
  "byDate": {
    "2026-05-27": {"runs": 450, "cost": 3.2}
  }
}

🔐 API Keys

GET/api/keys

Get configured API key status (does not return actual keys)

Requestcurl

curl https://promptshelf.ai/api/keys

Responsejson

{
  "providers": [
    {"provider": "deepseek", "configured": true, "maskedKey": "••••••••"},
    {"provider": "openai", "configured": false, "maskedKey": null},
    {"provider": "anthropic", "configured": false, "maskedKey": null}
  ]
}

POST/api/keys

Set API Key

Parameter	Type	Required	Description
provider	string	Yes	"deepseek" \| "openai" \| "anthropic"
apiKey	string	Yes	API Key (10-200 characters)

Setcurl

curl -X POST https://promptshelf.ai/api/keys \
  -H "Content-Type: application/json" \
  -d '{"provider": "deepseek", "key": "sk-your-api-key-here"}'

⚠️ Error Codes

Status Code	Description	Common Cause
`200`	Success	Request processed normally
`201`	CreateSuccess	Resource created
`400`	Bad Request	Missing parameters or format error
`401`	Unauthorized	Missing or invalid session token
`403`	Forbidden	No permission to perform this action
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource already exists (e.g. duplicate email)
`500`	Server error	Internal error, please retry

Error response formatjson

{
  "error": "API key not configured for openai"
}

📦 SDK

Use the official SDK for easier PromptShelf integration. Supports Python and Node.js.

🐍 Python SDK

Installbash

pip install promptshelf

Usagepython

from promptshelf import PromptShelf

client = PromptShelf(api_key="ps-sk-...")

# Execute Prompt
result = client.execute(
    prompt_id="p1",
    variables={"email": "Refund!"}
)
print(result.output)
print(f"Cost: {result.cost_usd} USD")

📦 Node.js SDK

Installbash

npm install @promptshelf/sdk

Usagetypescript

import { PromptShelf } from '@promptshelf/sdk';

const client = new PromptShelf({ apiKey: 'ps-sk-...' });

// Execute Prompt
const result = await client.execute({
  promptId: 'p1',
  variables: { email: 'Refund!' }
});
console.log(result.output);
console.log(`Cost: $${result.costUsd}`);

🔗 Direct REST API Calls

Don't want to use the SDK? Call the REST API directly. Any language that supports HTTP can integrate.

Python requestspython

import requests

response = requests.post(
    "https://promptshelf.ai/api/execute",
    json={
        "promptId": "p1",
        "variables": {"email": "Your service is terrible!"}
    }
)
data = response.json()
print(data["output"])

JavaScript fetchjavascript

const response = await fetch("https://promptshelf.ai/api/execute", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    promptId: "p1",
    variables: { email: "Your service is terrible!" }
  })
});
const data = await response.json();
console.log(data.output);

Ready to integrate?

3 minutes to integrate, free to start

🧪 Try Free ⚙️ Try the Playground