API Routes Map & Audit

Last Updated: August 20, 2026 Scope: All route handlers under src/app/api/ — 83 endpoints.

theunparty.app grew organically as a solo build, and the API surface is now large enough that it needs a single, shared picture before the user‑journey "game logic" gets wired on top of it. This document is that picture: what each route does, who calls it, how it's protected, and which routes are not wired to anything yet.

Every folder under src/app/api/<em></em> that contains a route.ts/route.tsx becomes a live HTTP endpoint (Next.js App Router). A [param] folder is a dynamic segment (e.g. book/[bookId]). Two files in the tree are not endpoints: book/[bookId]/route-old.ts (legacy, dead) and book/types.ts (shared types).

---

How traffic flows: who calls the API → which domain handles it → where the data lives.

---

Wiring — is the route actually reached, and by whom?

Auth — how the route is protected.

---

---

The core loop the user journey is built on: steps (tasks), the questions and challenges attached to them, and founder onboarding. This is the surface the new game logic will wire into, so its gaps matter most.

¹ founders/responses is restricted to a single identity via FOUNDER_USER_ID, not a Clerk role.

---

Records the journey so admins can see progress and retention. analytics/vercel is a drain endpoint and is listed again under Integrations.

---

Backs the /admin UI. Authorization here is inconsistent — see Audit finding B. 🛡️ = proper admin‑role check; ⚠️ = sign‑in only (any logged‑in user passes); ⛔ = no check at all.

---

Editorial articles, stories, and the dynamic social image. articles/stories are public to read but require STORY_API_KEY to write or to pull the full external feed.

---

Legacy book sales (Stripe) plus the current Polar checkout / pricing path. webhook/polar also appears under Integrations.

---

Read‑only data feeding the status dashboard and priority views. Three overlapping priority/effort endpoints exist — only priority-score is wired; see Audit finding A.

² repo-data is unauthenticated but reads through server‑side GitHub App credentials.

---

SVG library management, generic uploads, Apple Music tokens, and cached brand assets. The SVG routes read/write the local filesystem, which is ephemeral on Vercel — see Audit finding C.

---

---

Machine‑to‑machine endpoints. These are supposed to have no UI caller — they are driven by Vercel Cron, external webhooks, or Vercel drains, and each is signed/secret‑gated.

_Cron schedules live in vercel.json._

_Count note: webhook/polar and analytics/vercel are tallied under their primary domains (Commerce and Analytics) in At a glance and repeated here only to show the full machine‑to‑machine surface — so this table lists 9 rows for 7 unique Integrations‑owned endpoints._

---

No fetch, navigation, or external trigger references these anywhere in the repo. Each is a decision: wire it into the journey, or delete it.

_Not listed as orphans (intentionally UI‑less): cron/<em>, webhook/</em>, analytics/vercel, drains/traces (machine‑triggered); admin/questions/upload, admin/steps/sync-questions, music/mood-enrich (ops tools); stories (external API‑key feed)._

The /api/admin/* namespace mixes three different protection levels:

⛔ No auth at all — admin/steps/[id]/visibility (PATCH & POST) mutates step

visibility with zero authentication. Any anonymous caller can hide/show steps.

⚠️ Sign‑in only, no role check — admin/dashboard-stats, admin/db-stats,

admin/observability, admin/questions, admin/questions/[id], admin/question-responses, admin/repositories verify auth() has a userId but never call requireAdmin(). Any signed‑in user can read admin data (DB stats, observability, every user's responses) or mutate repositories.

🛡️ Correct — the remaining /api/admin/* routes use requireAdmin()

(src/lib/admin.ts → checkRole('admin')).

Recommendation: make requireAdmin() the single gate for the whole /api/admin/* namespace (ideally enforced in middleware.ts as well as per‑route), so protection can't drift route‑by‑route.

Unauthenticated writes. The SVG/asset and book/score/chat routes accept

writes with no auth. Acceptable for a solo build, but each is a public write path — gate them (or at least rate‑limit) before launch.

Naming is mostly consistent — verb‑style top‑level SVG routes

(get-svgs, delete-svg, …) sit alongside RESTful nested resources (steps/[id], admin/…). Fine to leave, but new routes should prefer the nested RESTful form.

Priority/effort duplication. unppp/priority, unppp/priority-score, and

unppp/effort overlap; consolidating removes a class of "which one is live?" bugs.

---

There is no test runner in this repo (see CLAUDE.md); this audit was produced by static inspection. To refresh it after changing routes:

List endpoints & methods — every exported GET/POST/PUT/PATCH/DELETE

handler (as export async function, export function, or export const) under src/app/api/<em></em>/route.ts(x).

Check wiring — search the repo (outside src/app/api/) for the route path in

fetch(...), href/window.location, <Image>/<img> src, vercel.json crons, and provider webhook configs. No hit → likely an orphan (finding A).

Check auth — look for requireAdmin(), auth(), STORY_API_KEY, CRON_SECRET,

or a signature verifier at the top of each handler.