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: 400 invalid body, 401 unauthorized, 500 Supabase hiccup.
  • GET /api/sources — Returns { sources: Source[] } for the authenticated user.

  • DELETE /api/sources/:id — Removes the source if you own it. 204 on 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 }.

Bookmarks

  • GET /api/bookmarks — Lists saved items. Requires session.
  • POST /api/bookmarks — Body { itemId: uuid }, returns 201 { id }.
  • DELETE /api/bookmarks/:itemId — Soft-delete for the user; returns 204.

Preferences

  • GET /api/preferences — Returns { preferences, focusTags } or 401 if not signed in.
  • POST /api/preferences — Body { focusWeight?, autoScrollIntervalMs?, theme?, showAiSummaries?, focusTopics? }, success 200 { 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.

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).