API Contracts

Three endpoints: listing (paginated, filterable), details, and the founder-led update endpoint (gated by ownership). Plus the moderation report endpoint (any user can flag a founder-led profile for review).

1 · GET /api/founders — listing

• Query params: q · country (csv) · sector (csv) · role (csv) · verified (bool) · flavor (all|editorial|founder-led) · sort (most-relevant|newest|alphabetical|most-mentioned) · page · pageSize · lang.
• Response: { items: FounderListItem[], totalCount, page, pageSize, filters: { applied, available }, counts: { total, verified, founderLed, editorial } }.
• FounderListItem: { id, slug, displayName, headline, role, country {code,name}, avatarUrl, isVerified, flavor, startupThumbnails[<=3], totalStartups, mentionCount }.
• Cache: public, max-age=180, s-maxage=300, stale-while-revalidate=900. Invalidate on Founder publish/update.

2 · GET /api/founders/{slug} — details

• Path: slug. Query: lang.
• Response: { ...Founder full, bio, skills[], languages[], startups[] (with role + dates), speakingHistory[], coverageMentions[], filesAuthored[], editorialArticlesAuthored[], relatedFounders[], seo {metaTitle, metaDescription, jsonLd}, isOwnerView (computed from auth) }.
• Each related-entity array capped server-side at 12; full lists available via /api/founders/{slug}/speaking?offset=12 etc.
• Cache: 300s public + 900s s-maxage. Invalidate on Founder update OR any cross-module link change touching this Founder.

3 · PATCH /api/founders/{id} — founder-led update

• Auth: required. Authorization: viewer.userId must equal Founder.OwnerUserId AND Founder.Flavor === 'founder-led'. 403 otherwise.
• Body: partial Founder fields (DisplayName, Headline, Bio, AvatarUrl, LinkedInUrl, TwitterUrl, PersonalSiteUrl, etc). Lang variant determined by ?lang param.
• Server: creates a versioned snapshot in FounderVersion table. 90-day restore window. Response: updated Founder shape + versionId.
• Rate limit: 10 PATCH/founder/hour (anti-vandalism).

4 · POST /api/founders/{id}/report — moderation flag

• Auth: optional (anonymous reports allowed for impersonation reports).
• Body: { reason: 'impersonation' | 'inaccurate' | 'offensive' | 'spam' | 'other', notes?: string }.
• Server: enqueues to admin moderation queue (§10.4). Rate-limited per IP.