API Endpoints
Base path: /api/clipdesk
| Method | Path | Auth | Purpose |
|---|
| POST | /auth/request-otp | Public | Request OTP via email |
| POST | /auth/verify-otp | Public | Verify OTP, get JWT |
| POST | /clients/register | Public | Register client/business |
| POST | /clients/:id/campaigns | JWT Client | Create campaign |
| GET | /clients/:id/dashboard | JWT Client | Client dashboard & stats |
| POST | /clippers/register | Public | Register clipper |
| GET | /clippers/marketplace | JWT | Browse active campaigns |
| POST | /clippers/:id/campaigns/:cid/join | JWT Clipper | Join campaign, get affiliate link |
| POST | /clippers/:id/clips/submit | JWT Clipper | Submit clip for phi scoring |
| GET | /clippers/:id/earnings | JWT Clipper | Earnings dashboard |
| GET | /clippers/:id/intelligence | JWT Clipper | World Model intelligence |
| GET | /creators/:id/intelligence | JWT | Creator analytics & DNA |
| GET | /track/:affiliateCode | Public | Affiliate link redirect |
| GET | /admin/revenue | Admin Key | Platform revenue analytics |
| GET | /admin/campaigns | Admin Key | All campaigns overview |
| POST | /admin/conversions/process | Admin Key | Process conversion manually |
| POST | /admin/outreach/pitch | Admin Key | Generate sales pitch |
| POST | /whop/webhook | Public | Whop payment webhook |
| POST | /whop/checkout | JWT | Create Whop checkout link |
| POST | /whop/checkout-config | JWT | Embedded checkout config |
| GET | /health | Public | Health check + config verify |
Phi Scoring Formula
Viral Score =
(0.40 × Engagement Velocity)
+ (0.25 × View-to-Like Ratio)
+ (0.20 × Retention Rate)
+ (0.10 × Hashtag Relevance)
+ (0.05 × Soundtrack/Filter Impact)
Threshold: φ = 1.618033988875 (Golden Ratio)
Qualified: score ≥ φ
Gap: phi_gap = φ - score (for non-qualified clips)
| Metric | Weight | What It Measures |
|---|
| Engagement Velocity | 40% | Speed of engagement growth after posting |
| View-to-Like Ratio | 25% | Percentage of viewers who liked |
| Retention Rate | 20% | How much of the video viewers watch |
| Hashtag Relevance | 10% | Campaign & trend alignment |
| Soundtrack/Filter Impact | 5% | Trending sounds & effects usage |
Commission Splits
Clipper 20%
Platform 10%
Client 70%
| Product Price | Clipper (20%) | ViralVid (10%) | Client (70%) |
|---|
| R149 | R29.80 | R14.90 | R104.30 |
| R299 | R59.80 | R29.90 | R209.30 |
| R2,500 | R500.00 | R250.00 | R1,750.00 |
Payout threshold: R50 ZAR minimum pending before payout eligible.
OTP Authentication Flow
1. Client/Clipper registers (POST /clients/register or /clippers/register)
↓
2. Request OTP (POST /auth/request-otp)
Body: { email, userType: "client" | "clipper" }
↓
3. System generates 6-digit OTP → hashes with SHA-256 → stores hash + expiry (10 min)
↓
4. OTP emailed via Resend (from: noreply@viralvid.io)
↓
5. Verify OTP (POST /auth/verify-otp)
Body: { email, otp, userType }
↓
6. System hashes input → compares → checks expiry
↓
7. On success: OTP cleared, JWT issued (7-day expiry)
Response: { token, user: { id, role, email } }
Rate limits: 5 OTP requests/hour per email | 100 verifications/15 min global
Role Permissions Matrix
| Action | Client | Clipper | Admin |
|---|
| Register | ✓ | ✓ | N/A (key-based) |
| OTP Login | ✓ | ✓ | N/A |
| Create Campaigns | ✓ | ✗ | ✗ |
| View Client Dashboard | ✓ | ✗ | ✗ |
| Browse Marketplace | ✗ | ✓ | ✗ |
| Join Campaigns | ✗ | ✓ | ✗ |
| Submit Clips | ✗ | ✓ | ✗ |
| View Earnings | ✗ | ✓ | ✗ |
| View Intelligence | ✗ | ✓ | ✗ |
| Process Conversions | ✗ | ✗ | ✓ |
| View Revenue | ✗ | ✗ | ✓ |
| View All Campaigns | ✗ | ✗ | ✓ |
| Generate Pitches | ✗ | ✗ | ✓ |
Environment Variables
| Variable | Required | Default | Notes |
|---|
DATABASE_URL | Yes | — | PostgreSQL connection string |
JWT_SECRET | Yes | — | Min 32 characters |
JWT_EXPIRY | No | 7d | Token expiration |
PORT | No | 3001 | Server port |
NODE_ENV | No | development | development | production |
PHI | No | 1.618033988875 | Hardcoded, throws if changed |
CLIPPER_COMMISSION_PERCENT | No | 20 | Must sum to 100 with others |
VIRALVID_REV_SHARE_PERCENT | No | 10 | Must sum to 100 with others |
CLIENT_KEEP_PERCENT | No | 70 | Must sum to 100 with others |
PAYOUT_THRESHOLD_ZAR | No | 50 | Min ZAR for payout |
RESEND_API_KEY | Yes | — | Email service API key |
EMAIL_FROM | No | noreply@viralvid.io | OTP sender address |
OTP_EXPIRY_MINUTES | No | 10 | OTP validity window |
ADMIN_API_KEY | Yes | — | Admin authentication |
ALLOWED_ORIGINS | No | http://localhost:3000 | CORS origins (comma-sep) |
WHOP_API_KEY | No | "" | Whop MoR API key |
WHOP_BUSINESS_ID | No | "" | Whop business ID |
Key URLs & Health Check
| URL | Purpose |
|---|
http://localhost:3001/ | Marketing landing page |
http://localhost:3001/training/ | Training hub |
http://localhost:3001/cheatsheet.html | This cheat sheet |
http://localhost:3001/api/clipdesk/health | API health check |
http://localhost:3001/robots.txt | Robots.txt |
http://localhost:3001/llms.txt | AI discoverability metadata |
http://localhost:3001/schema.json | Schema.org markup |
http://localhost:3001/legal/terms.html | Terms of Service |
http://localhost:3001/legal/privacy.html | Privacy Policy |
http://localhost:3001/legal/rev-share.html | Rev Share Agreement |
Health Check Response
GET /api/clipdesk/health
{
"status": "ok",
"database": "connected",
"phi": 1.618033988875,
"phiVerified": true,
"splits": { "clipper": 20, "platform": 10, "client": 70 },
"uptime": 12345,
"timestamp": "2026-02-26T..."
}