Reference: API
When in doubt, this is the canonical map of our Next.js API routes. Every handler lives under web/src/app/api/* and leans on zod for validation.
Sources
-
POST
/api/sources— Add RSS or X sources.- Body:
{ type?: 'rss'|'twitter', url?: string, handle?: string, displayName?: string } - Success:
201 { source, ingestion } - Errors:
400invalid body,401unauthorized,500Supabase hiccup.
- Body:
-
GET
/api/sources— Returns{ sources: Source[] }for the authenticated user. -
DELETE
/api/sources/:id— Removes the source if you own it.204on success.
Feed
- GET
/api/feed— Primary feed endpoint.- Query:
limit=1..100(default 20),before=ISO timestamp,mixRatio=0..1(default 0.7). - Response:
{ items: Item[], nextCursor: ISO|null }.
- Query:
Bookmarks
- GET
/api/bookmarks— Lists saved items. Requires session. - POST
/api/bookmarks— Body{ itemId: uuid }, returns201 { id }. - DELETE
/api/bookmarks/:itemId— Soft-delete for the user; returns204.
Preferences
- GET
/api/preferences— Returns{ preferences, focusTags }or401if not signed in. - POST
/api/preferences— Body{ focusWeight?, autoScrollIntervalMs?, theme?, showAiSummaries?, focusTopics? }, success200 { success: true }.
AI
- GET
/api/ai/key— Whether the user has a stored Gemini key. - POST
/api/ai/key— Save{ provider?: 'gemini', apiKey }. - DELETE
/api/ai/key— Remove the stored key. - POST
/api/ai/summarize— Body{ itemId: uuid, force?: boolean }, response{ summary, cached }.
Cron triggers
- GET/POST
/api/cron/rss - GET/POST
/api/cron/x- In production, both require
x-cron-secret: <CRON_SECRET>header.
- In production, both require
Error codes
400— Validation failed (zod catches).401— Session missing or expired.403— Forbidden; usually a row doesn’t belong to you.500/502— Upstream failure (Supabase, Gemini, or fetch error).