---
title: "api-audit"
description: "Use when auditing API routes for schema drift, missing auth, or validation gaps. Scans routes against shared TypeScript types to find mismatches, missing middleware, and undocumented endpoints. Read-only — produces a severity-grouped report. Keywords: audit routes, schema drift, auth gaps, missing validation, type mismatch, orphaned schemas. Triggers on \"audit API routes\" or \"find schema drift\"."
canonical_url: "https://skilld.dev/gh/acedergren/agentic-tools/api-audit"
last_updated: "2026-09-24T08:36:36.000Z"
---

---
name: api-audit
description: "Use when auditing API routes for schema drift, missing auth, or validation gaps. Scans routes against shared TypeScript types to find mismatches, missing middleware, and undocumented endpoints. Read-only — produces a severity-grouped report. Keywords: audit routes, schema drift, auth gaps, missing validation, type mismatch, orphaned schemas. Triggers on "audit API routes" or "find schema drift"."
---

> **Skill from skilld.dev.** Follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [scripts/find-shared-schemas.sh](https://skilld.dev/api/skills-raw/acedergren/agentic-tools/api-audit/scripts/find-shared-schemas.sh), [scripts/inventory-api-surface.sh](https://skilld.dev/api/skills-raw/acedergren/agentic-tools/api-audit/scripts/inventory-api-surface.sh).
>
> If the user asked to install this Skill, run `npx skilld install acedergren/agentic-tools/api-audit`. Install writes the Skill files into the project, so every session loads them.

# API Route & Type Audit Skill

## When to Use

Load this skill when the user request matches the frontmatter description for 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
bash scripts/inventory-api-surface.sh
bash scripts/inventory-api-surface.sh admin   # scope filter
bash scripts/find-shared-schemas.sh packages
```

## What 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:
1. **Critical**: Auth gaps on mutation endpoints, missing request validation on write operations
2. **Warning**: Type drift between route handler and shared schema, missing response schemas on documented APIs
3. **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.

## Arguments

$ARGUMENTS: Optional user-provided target, path, environment, symptom, or constraint. When empty, infer the narrowest safe scope from the current repository context and ask only if multiple high-impact choices remain.