API

Evaluate prompts, gate regression in CI, and serve production versions over HTTP. Open on every plan.

Authentication

Authorization: Bearer pe_live_your_key_here

Plans & quota

Endpoint

json{
  "prompt": "Your prompt text here",
  "mode": "lint",
  "language": "en"
}

Response

json{
  "mode": "lint",
  "score": 74,
  "dimensions": {
    "clarity": 68,
    "specificity": 81,
    "structure": 77,
    "robustness": 70
  },
  "conflicts": [
    { "a": "Be concise", "b": "Explain in full detail", "type": "contradiction" }
  ],
  "benchmark": { "top_percent": 22, "total": 1840 },
  "pass": false,
  "min_score": 75,
  "meta": {
    "prompt_chars": 1240,
    "evaluated_at": "2026-06-04T14:32:00Z",
    "plan": "pro",
    "byok": false,
    "calls_month": 12,
    "quota_month": 75,
    "quota_remaining": 63
  }
}

json{
  "mode": "full",
  "score": 74,
  "dimensions": { "clarity": 68, "specificity": 81, "structure": 77, "robustness": 70 },
  "conflicts": [ /* ... */ ],
  "benchmark": { "top_percent": 22, "total": 1840 },
  "pass": false,
  "min_score": 75,
  "graph": { "nodes": [ /* ... */ ], "edges": [ /* ... */ ] },
  "problems": {
    "critical": ["Output format is underspecified."],
    "warnings": ["Persona may conflict with the tone constraint."]
  },
  "recommendations": [
    "Add an explicit output-format section with an example.",
    "Reconcile the tone constraint with the persona."
  ],
  "improved_prompt": "You are a customer support agent...",
  "meta": { "plan": "pro", "byok": false, "calls_month": 13, "quota_month": 75, "quota_remaining": 62 }
}

CI gate (the pass field)

json"regression": {
  "baseline": { "slug": "support-agent" },
  "baseline_score": 82,
  "current_score": 74,
  "delta": -8,
  "max_drop": 0,
  "regressed": true
}

Errors

json{ "error": "machine_code", "message": "Human-readable description." }

BYOK — bring your own key

bash# BYOK: run on your own Anthropic key.
# No managed quota is consumed, and it unlocks "full" on any plan.
curl -X POST https://prompt-eval.com/api/v1/eval \
  -H "Authorization: Bearer pe_live_your_key_here" \
  -H "X-Provider-Key: sk-ant-your-anthropic-key" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "You are a customer support agent...", "mode": "full" }'

Examples

bashcurl -X POST https://prompt-eval.com/api/v1/eval \
  -H "Authorization: Bearer pe_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "You are a customer support agent. Answer clearly and concisely. Always end by asking if there is anything else you can help with.",
    "mode": "lint"
  }'

CI/CD integration

yaml# .github/workflows/prompt-check.yml
name: Prompt Check
on:
  pull_request:
    paths: ['prompts/**']   # adjust to your prompts directory
jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: FranciscoFerreiraff/prompteval-action@v1
        with:
          api_key: ${{ secrets.PROMPTEVAL_API_KEY }}
          prompt_file: prompts/support-agent.md
          min_score: 75
          fail_on_conflict: true
          baseline_slug: support-agent   # gate regression vs production

Prompts API (serving)

Examples

bashcurl https://prompt-eval.com/api/v1/prompts/customer-support \
  -H "Authorization: Bearer pe_live_your_key_here"

Risk mitigation

python# ❌ NÃO faça isso — você depende 100% do PromptEval em produção
def handle_request(user_input):
    prompt = get_from_prompteval("customer-support")  # falha se a API cair
    return call_llm(prompt, user_input)

python# ✅ Faça isso — fallback local garante uptime
FALLBACK_PROMPT = "You are a helpful assistant..."  # versão hardcoded de emergência

def handle_request(user_input):
    try:
        prompt = get_from_prompteval("customer-support")
    except Exception:
        prompt = FALLBACK_PROMPT  # nunca para de funcionar
    return call_llm(prompt, user_input)

javascript// ✅ JavaScript — fallback local
const FALLBACK_PROMPT = "You are a helpful assistant...";

async function getPrompt(slug) {
  try {
    const res = await fetch(
      `https://prompt-eval.com/api/v1/prompts/${slug}`,
      { headers: { Authorization: `Bearer ${process.env.PROMPTEVAL_API_KEY}` } }
    );
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const data = await res.json();
    return data.content;
  } catch {
    return FALLBACK_PROMPT; // nunca para de funcionar
  }
}

Response — 200

json{
  "slug": "customer-support",
  "name": "Customer Support Agent",
  "version": 3,
  "content": "You are a customer support agent...",
  "score": 82,
  "production_set_at": "2026-05-14T10:00:00Z"
}

Errors

Need higher quota? Contact us — we offer custom plans for high-volume teams. → francisco@prompt-eval.com

Missing something in the docs? Open an issue or send feedback →