API Reference
All API endpoints are Vercel serverless functions located in the api/ directory. They follow RESTful conventions and use JSON for request/response bodies.
Base URL
Production: https://kinetic.email/api
Local: http://localhost:5173/api
Authentication
Most endpoints require a Supabase JWT in the Authorization header:
Authorization: Bearer <supabase-jwt>
See Authentication for details on obtaining and using tokens.
Common Response Patterns
Success
{
"success": true,
"data": { ... }
}
Error
{
"error": "Human-readable error message"
}
HTTP Status Codes
| Code | Meaning |
|---|---|
200 | Success |
400 | Bad request (missing/invalid parameters) |
401 | Unauthorized (missing or invalid JWT) |
402 | Payment required (insufficient tokens) |
403 | Forbidden (admin access required) |
405 | Method not allowed |
500 | Internal server error |
Endpoint Summary
Public Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/track-pixel | GET | None | Tracking pixel for email opens/interactions (Edge runtime) |
/api/track-amp-event | POST | None | AMP interaction event logging (Edge runtime) |
/api/view-email | GET | None | Hosted "View in Browser" page by send ID |
/api/validate-amp | POST | None | Validate AMP4Email HTML (CORS-restricted) |
/api/blog-og | GET | None | Dynamic Open Graph image generation |
User Endpoints
| Endpoint | Method | Auth | Tokens | Description |
|---|---|---|---|---|
/api/gen/copy | POST | User | — | Stage 1: finalized email copy (Claude Haiku) |
/api/gen/blueprint | POST | User | — | Stage 2: structural blueprint + design tokens (Claude Haiku) |
/api/generate | POST | User | ai_generation | Stage 3: full email code generation (RAG pipeline, Claude Sonnet) |
/api/generate-email | POST | User | ai_generation | Simple AI email generation / refine (no RAG) |
/api/send-email-mailgun | POST | User | — | Send email via Mailgun (AMP support, suppression-checked) |
/api/unsubscribe | POST | User or signed link token | — | Global unsubscribe (Bearer session or HMAC link token) |
Webhook Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/mailgun-webhook | POST | Mailgun HMAC (required) | Delivery events, bounces, complaints from Mailgun |
/api/notify-signup | POST | x-webhook-secret header | Supabase Database Webhook → Telegram signup alert |
Admin Endpoints
| Endpoint | Method | Auth | Description |
|---|---|---|---|
/api/admin/submit-content | POST | Admin | Upload content to RAG (Pinecone + Supabase) |
/api/admin/update-content | POST | Admin | Update RAG content |
/api/admin/delete-content | POST | Admin | Delete from RAG |
/api/admin/list-content | GET | Admin | Browse RAG library |
/api/admin/rag-stats | GET | Admin | RAG database statistics |
/api/admin/auto-tag | POST | Admin | AI content auto-tagging |
/api/admin/eval | GET/POST | Admin | Eval harness runs/results (createRun, saveResult, finalizeRun) |
/api/eval/judge | POST | Admin | LLM judge scoring for eval harness |
/api/admin/submit-feedback | POST | Admin | Submit generation feedback |
/api/deploy-email | POST | Admin | Deploy showcase email HTML to production |
CORS
API endpoints are restricted to the following origins:
https://kinetic.email
https://www.kinetic.email
http://localhost:5173
http://localhost:3000