API Route & Type Audit Skill
Read-only cross-reference of API routes against shared type definitions. Do NOT modify any files.
NEVER
- Never flag a missing schema without first confirming the framework doesn't use inline validation (Fastify schema objects, Zod in middleware, etc.).
- Never report an auth gap without verifying the route should actually be protected — not all routes require auth.
- Never treat orphaned types as critical — they may be planned, transitional, or used by SDK consumers not visible in the route tree.
- Never make assumptions about auth from route path alone —
/admin/*prefix doesn't guarantee a route requires auth without inspecting the hook chain.
Decision: What counts as a real mismatch?
Schema drift — only if the shared type and the route handler both exist but disagree on shape (field names, required vs optional, type divergence). A route using its own inline schema is not drift.
Auth gap — only if: (a) a sibling or parent route has auth hooks AND (b) the route handles mutations or user-scoped data. Public GET endpoints with no sibling pattern are ambiguous — report as Info, not Critical.
Orphaned type — only if the schema has no imports, no references in any route file, and is not in a types/ package that may serve external consumers.
Parallel Execution Strategy
Spawn two agents simultaneously:
- Agent A: Scan routes + plugins → catalog
(method, path, auth hooks, request schema, response schema)per endpoint - Agent B: Scan type/schema directories → catalog all exported schema names and their shapes
Synthesize after both complete. Never do this serially — the two inventories are independent.
Scripts
bash scripts/inventory-api-surface.sh
bash scripts/inventory-api-surface.sh admin # scope filter
bash scripts/find-shared-schemas.sh packagesWhat to Collect (Agent A)
Per route: HTTP method, path, auth/permission requirements, request validation schema (name or inline), response schema (name or inline). Check both route registration AND plugin/middleware hooks — auth often lives in the plugin, not the handler.
What to Collect (Agent B)
Per shared schema: exported name, file location, TypeScript shape summary, and whether it's referenced by any route import.
Report Format
Severity-grouped markdown table:
| Severity | Category | Route/Type | Issue | File:Line |
|---|
Severity levels:
- Critical: Auth gaps on mutation endpoints, missing request validation on write operations
- Warning: Type drift between route handler and shared schema, missing response schemas on documented APIs
- Info: Orphan types, inline schemas that could use shared ones
Include summary counts: total routes, full validation coverage, partial, none, mismatch count.
Scope Filter
$ARGUMENTS — optional path prefix (e.g., admin → only audit /admin/* routes). Empty = audit all.