API Contracts

Four endpoints: listing, details, lead-capture (POST), and reader-session telemetry (POST). Lead-capture is rate-limited and has strict consent validation.

1 · GET /api/founder-files

• Query: category? · topic? · sort (newest|featured-first|most-downloaded) · page · pageSize · lang.
• Response items: { id, slug, number, title, bestForTagline, category, topics[], readingTimeMinutes, coverImageUrl, hasSponsor (bool), sponsor {name, logoUrl}?, isFeatured, downloadCount }.
• Cache: 300s public + 900s s-maxage.

2 · GET /api/founder-files/{slug}

• Query: lang · variant ('details' | 'reader', default 'details'). variant='reader' returns the full ReaderBodyHtml; variant='details' omits it (the body is large, save bandwidth on the marketing surface).
• Response: { ...FounderFile core, title, bestForTagline, subtitle?, learningPoints[], bestForBullets[], artifacts[], authors[] (Founder cards), topics[], sponsor?, readerBodyHtml? (when variant=reader), connectedSignals[], relatedFiles[], seo {metaTitle, metaDescription, jsonLd} }.
• Cache: 600s public + 1800s s-maxage.

3 · POST /api/founder-files/{id}/leads — consent-gated capture

• Body: { email, name, role, country, stage?, consentPlatform (must be true), consentPartners (default false), source: 'details' | 'reader' }.
• Server: validates email + consentPlatform=true, writes FounderFileLead row (with IP + UserAgent captured), increments DownloadCount, queues download email + sponsor-CRM webhook if consentPartners=true.
• Rate limit: 5 leads/IP/hour. 422 with field errors on validation fail. 429 on rate-limit hit.
• Response: 201 { leadId, downloadCount (post-increment) }.

4 · POST /api/founder-files/{id}/reader-telemetry

• Body: { sessionId, scrollDepthPct (0-100), completed (bool), durationMs }. Anonymous when no lead. Idempotent on (sessionId, fileId).
• Fires on visibility-change + scroll milestones (25/50/75/complete). Server writes/updates FounderFileReadSession.