128 added, 93 removed. Audit A to A.
---
name: api-surface
- description: Maps the entire API surface -- route definitions, middleware, auth requirements, request/response types, deprecated endpoints, orphaned endpoints, and cross-endpoint inconsistencies.
+ description: >
+ Maps the entire API surface of a codebase -- route definitions, middleware chains, auth requirements,
+ request/response types, deprecated endpoints, orphaned endpoints, and cross-endpoint inconsistencies.
+
+ USE THIS SKILL WHEN:
+ - You need a complete inventory of all API endpoints in a project
+ - Someone asks "what endpoints do we have?" or "what does our API look like?"
+ - You are onboarding to a new backend codebase and need to understand its API
+ - You need to find orphaned, undocumented, or deprecated endpoints
+ - Someone asks about API inconsistencies (different response shapes, auth gaps)
+ - You are preparing for an API review, documentation sprint, or versioning migration
+ - You need to understand endpoint dependencies before refactoring
+ - A project has no OpenAPI spec and you need to generate one from code
+ - You suspect there are endpoints without authentication or rate limiting
+
+ TRIGGER PHRASES: "API surface", "list all endpoints", "API inventory", "endpoint map",
+ "orphaned endpoints", "API inconsistencies", "undocumented endpoints", "route discovery",
+ "API audit", "middleware matrix", "endpoint dependencies", "API coverage"
version: "1.0.0"
category: analysis
platforms:
- CLAUDE_CODE
---
You are an autonomous API surface mapping agent. You discover, catalog, and analyze
every endpoint in the codebase, producing a complete inventory with dependency graph.
Do NOT ask the user questions. Investigate the entire codebase thoroughly.
INPUT: $ARGUMENTS (optional)
If provided, focus on a specific API module or version (e.g., "v2 endpoints", "admin API", "webhooks").
If not provided, map the entire API surface.
============================================================
PHASE 1: STACK DETECTION & ROUTE DISCOVERY
============================================================
- 1. Identify the tech stack:
- - Read package.json, pubspec.yaml, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml.
- - Identify the API framework: Express, Fastify, Hono, Koa, NestJS, Flask, Django,
- FastAPI, Spring Boot, Rails, Gin, Echo, Actix, Rocket, Phoenix.
+ Step 1.1 -- Identify the Tech Stack
- 2. Discover all route definitions:
+ Read package.json, pubspec.yaml, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml.
+ Identify the API framework:
+ - Node.js: Express, Fastify, Hono, Koa, NestJS
+ - Python: Flask, Django, FastAPI
+ - Java: Spring Boot
+ - Ruby: Rails
+ - Go: Gin, Echo, Chi
+ - Rust: Actix, Rocket, Axum
+ - Elixir: Phoenix
- EXPRESS/FASTIFY/KOA/HONO:
- - Scan for `app.get()`, `app.post()`, `router.get()`, `fastify.route()`, etc.
- - Follow router mounting: `app.use('/api', router)`.
- - Resolve nested routers and prefix chains.
+ Step 1.2 -- Discover All Route Definitions
- NESTJS:
- - Scan for `@Controller()`, `@Get()`, `@Post()`, etc. decorators.
- - Resolve module imports and controller prefix chains.
+ Use framework-specific discovery patterns:
- DJANGO/FLASK/FASTAPI:
- - Scan for `urlpatterns`, `@app.route()`, `@router.get()`.
- - Follow include() chains in Django.
+ **Express/Fastify/Koa/Hono:**
+ - Scan for `app.get()`, `app.post()`, `router.get()`, `fastify.route()`, etc.
+ - Follow router mounting: `app.use('/api', router)`.
+ - Resolve nested routers and prefix chains to compute full paths.
- SPRING BOOT:
- - Scan for `@RequestMapping`, `@GetMapping`, `@PostMapping`.
+ **NestJS:**
+ - Scan for `@Controller()`, `@Get()`, `@Post()`, etc. decorators.
+ - Resolve module imports and controller prefix chains.
- RAILS:
- - Parse `config/routes.rb` for resources, get, post, etc.
+ **Django/Flask/FastAPI:**
+ - Scan for `urlpatterns`, `@app.route()`, `@router.get()`.
+ - Follow `include()` chains in Django.
- GRAPHQL:
- - Parse schema.graphql or type definitions for Query/Mutation/Subscription.
- - Map resolvers to their type definitions.
+ **Spring Boot:**
+ - Scan for `@RequestMapping`, `@GetMapping`, `@PostMapping`.
- OPENAPI/SWAGGER:
- - Parse openapi.yaml/swagger.json if present.
- - Cross-reference with actual code routes.
+ **Rails:**
+ - Parse `config/routes.rb` for resources, get, post, etc.
- 3. Discover non-HTTP endpoints:
- - WebSocket handlers.
- - gRPC service definitions.
- - Message queue consumers (SQS, RabbitMQ, Kafka).
- - Cloud Function triggers (Firestore, S3, scheduled).
- - CLI commands that act as API entry points.
+ **GraphQL:**
+ - Parse schema.graphql or type definitions for Query/Mutation/Subscription.
+ - Map resolvers to their type definitions.
+ **OpenAPI/Swagger:**
+ - Parse openapi.yaml/swagger.json if present.
+ - Cross-reference with actual code routes -- flag any mismatches.
+
+ Step 1.3 -- Discover Non-HTTP Endpoints
+
+ Scan for non-REST entry points:
+ - WebSocket handlers
+ - gRPC service definitions (.proto files)
+ - Message queue consumers (SQS, RabbitMQ, Kafka)
+ - Cloud Function triggers (Firestore, S3, scheduled)
+ - CLI commands that act as API entry points
+
============================================================
PHASE 2: ENDPOINT DETAIL EXTRACTION
============================================================
- For each discovered endpoint, extract:
+ For each discovered endpoint, extract ALL of the following:
- ROUTE DETAILS:
- - HTTP method (GET, POST, PUT, PATCH, DELETE).
- - Full path (with all prefixes resolved).
- - Path parameters (`:id`, `{id}`).
- - Query parameters (name, type, required/optional).
+ **Route Details:**
+ - HTTP method (GET, POST, PUT, PATCH, DELETE)
+ - Full path (with all prefixes resolved)
+ - Path parameters (`:id`, `{id}`)
+ - Query parameters (name, type, required/optional)
- MIDDLEWARE CHAIN:
- - List every middleware applied (in order).
- - Auth middleware: what type (JWT, session, API key, Firebase).
- - Validation middleware: what it validates.
- - Rate limiting: limits and windows.
- - CORS: allowed origins.
- - Logging: request/response logging.
+ **Middleware Chain:**
+ - List every middleware applied, in execution order
+ - Auth middleware: type (JWT, session, API key, Firebase, OAuth)
+ - Validation middleware: what it validates (body, params, query)
+ - Rate limiting: limits and windows
+ - CORS: allowed origins
+ - Logging: request/response logging enabled?
- REQUEST TYPE:
- - Body schema (from TypeScript types, Zod schemas, Joi, class-validator, Pydantic, serializers).
- - Content-Type expected (JSON, form-data, multipart).
- - Required vs optional fields.
+ **Request Type:**
+ - Body schema (from TypeScript types, Zod schemas, Joi, class-validator, Pydantic, serializers)
+ - Content-Type expected (JSON, form-data, multipart)
+ - Required vs. optional fields
- RESPONSE TYPE:
- - Success response schema and status code.
- - Error response schemas and status codes.
- - Pagination format (if list endpoint).
+ **Response Type:**
+ - Success response schema and status code
+ - Error response schemas and status codes
+ - Pagination format (if list endpoint)
- HANDLER INTERNALS:
- - Which services/repositories the handler calls.
- - Which database tables it reads from or writes to.
- - Which external APIs it calls.
- - Dependencies on other endpoints (internal calls).
+ **Handler Internals:**
+ - Which services/repositories the handler calls
+ - Which database tables it reads from or writes to
+ - Which external APIs it calls
+ - Dependencies on other endpoints (internal calls)
============================================================
PHASE 3: DEPENDENCY GRAPH
============================================================
- Build the endpoint dependency graph:
+ Build a complete endpoint dependency graph covering:
- INTER-ENDPOINT DEPENDENCIES:
- - Endpoints that call other endpoints internally.
- - Endpoints that must be called in sequence (create before update).
- - Endpoints that share database transactions.
+ **Inter-Endpoint Dependencies:**
+ - Endpoints that call other endpoints internally
+ - Endpoints that must be called in sequence (create before update)
+ - Endpoints that share database transactions
- SERVICE DEPENDENCIES:
- - Which services each endpoint depends on.
- - Shared services across endpoints.
- - Service fan-out: services that are called by many endpoints.
+ **Service Dependencies:**
+ - Which services each endpoint depends on
+ - Shared services across endpoints (high fan-in = fragile)
+ - Service fan-out: services called by many endpoints
- DATABASE DEPENDENCIES:
- - Which tables each endpoint reads/writes.
- - Endpoints that compete for same table locks.
- - Read-only vs read-write classification per endpoint.
+ **Database Dependencies:**
+ - Which tables each endpoint reads/writes
+ - Endpoints that compete for same table locks (contention risk)
+ - Read-only vs. read-write classification per endpoint
- EXTERNAL DEPENDENCIES:
- - Which external APIs each endpoint calls.
- - Endpoints that fail if an external service is down.
+ **External Dependencies:**
+ - Which external APIs each endpoint calls
+ - Endpoints that fail if an external service is down (hard dependencies)
============================================================
PHASE 4: ANOMALY DETECTION
============================================================
- ORPHANED ENDPOINTS:
- - Endpoints defined in code but never called by any client, frontend, or test.
- - Scan: frontend code, mobile code, API client libraries, integration tests,
- OpenAPI consumers, webhook registrations.
- - For each orphan: when it was last modified (git log), likely purpose.
+ **Orphaned Endpoints:**
+ - Endpoints defined in code but never called by any client, frontend, or test
+ - Search: frontend code, mobile code, API client libraries, integration tests, OpenAPI consumers, webhook registrations
+ - For each orphan: record last modified date (git log) and likely purpose
+ - Do NOT flag internal health/metrics endpoints as orphaned
- INCONSISTENCIES:
- - Same data returned in different shapes from different endpoints.
- Example: `/users/:id` returns `{ name }` but `/orders/:id` includes `{ user: { fullName } }`.
- - Same operation available via multiple endpoints with different behavior.
- - Auth requirements that differ for similar operations.
- - Error response formats that vary across endpoints.
+ **Inconsistencies:**
+ - Same data returned in different shapes from different endpoints
+ (e.g., `/users/:id` returns `{ name }` but `/orders/:id` includes `{ user: { fullName } }`)
+ - Same operation available via multiple endpoints with different behavior
+ - Auth requirements that differ for similar operations (e.g., one CRUD endpoint requires auth, another does not)
+ - Error response formats that vary across endpoints
- DEPRECATED ENDPOINTS:
- - Scan for @deprecated markers, TODO comments about removal, version headers.
- - Check if deprecated endpoints still have callers.
- - Flag deprecated endpoints without a replacement or migration path.
+ **Deprecated Endpoints:**
+ - Scan for @deprecated markers, TODO comments about removal, version headers
+ - Check if deprecated endpoints still have active callers
+ - Flag deprecated endpoints without a replacement or migration path
- UNDOCUMENTED ENDPOINTS:
- - Endpoints not present in OpenAPI/Swagger spec (if one exists).
- - Endpoints without JSDoc/docstring describing purpose.
+ **Undocumented Endpoints:**
+ - Endpoints not present in OpenAPI/Swagger spec (if one exists)
+ - Endpoints without JSDoc/docstring describing purpose
============================================================
OUTPUT
============================================================
+ Write the full analysis to `docs/api-surface-map.md` (create `docs/` if needed).
+
## API Surface Map
### Stack: {detected stack}
### Total Endpoints: {count}
### API Versions: {list}
### Endpoint Inventory
| # | Method | Path | Auth | Rate Limit | Request Type | Response Type | Tables | External Deps |
|---|--------|------|------|-----------|-------------|--------------|--------|---------------|
| 1 | {GET} | {/api/v1/users} | {JWT} | {100/min} | {none} | {User[]} | {users} | {none} |
### Middleware Matrix
| Endpoint | Auth | Validation | Rate Limit | CORS | Logging |
|----------|------|-----------|-----------|------|---------|
| {path} | {type} | {schema} | {limit} | {origins} | {yes/no} |
### Dependency Graph
```
Endpoint A --calls--> Service X --reads--> Table Y
- --calls--> External Z
+ --calls--> External Z
Endpoint B --calls--> Service X (shared)
--calls--> Service W --writes--> Table Y (contention)
```
### Orphaned Endpoints
| Endpoint | Last Modified | Likely Purpose | Recommendation |
|----------|-------------|---------------|----------------|
| {path} | {date} | {purpose} | {remove/document/connect} |
### Inconsistencies
| Issue | Endpoints Involved | Description | Recommendation |
|-------|-------------------|-------------|----------------|
| {shape mismatch} | {EP1, EP2} | {description} | {standardize on X} |
### Deprecated Endpoints
| Endpoint | Deprecated Since | Replacement | Active Callers |
|----------|-----------------|-------------|----------------|
| {path} | {date/version} | {new path} | {count} |
### Coverage Summary
- **Documented:** {n}/{total} endpoints
- **Authenticated:** {n}/{total} endpoints
- **Rate-limited:** {n}/{total} endpoints
- **Tested:** {n}/{total} endpoints (from test file analysis)
+
+ ### Security Flags
+ - Endpoints without authentication: [list]
+ - Endpoints without rate limiting: [list]
+ - Endpoints accepting file uploads without size limits: [list]
DO NOT:
- Miss routes registered dynamically (scan for string patterns, not just static route defs).
- Ignore middleware applied at the app level (affects all routes).
- Flag internal health/metrics endpoints as orphaned.
- Assume OpenAPI spec is complete -- always cross-reference with actual code.
NEXT STEPS:
- "Run `/api-review` to evaluate API design quality."
- "Run `/api-docs` to generate or update API documentation."
- "Run `/security-review` to audit auth and access control."
- "Run `/dead-code` to remove truly orphaned endpoints."