---

name: api-endpoint-scaffold description: Scaffold new Next.js API endpoints with authentication, rate limiting, and tests. Use when creating new API routes, adding endpoints, or building API features. allowed-tools: Read, Grep, Glob, Write, Edit

API Endpoint Scaffold

Creates production-ready API endpoints following this repo's patterns.

When to Use

• "Create an endpoint for..."
• "Add API route for..."
• "I need a POST/GET endpoint"
• "Build an API for {feature}"

Prerequisites

Before creating an endpoint, confirm:

1. Endpoint path (e.g., /api/users/profile)
2. HTTP methods needed (GET, POST, PUT, DELETE)
3. Authentication required? (default: yes)
4. Rate limiting config (requests/window)
5. Request/response schema

Procedure

Step 1: Create Route File

Path: apps/web/app/api/{path}/route.ts

Use the template in templates.md.

Step 2: Add Rate Limiting (if needed)

Import from existing pattern:

import { withUserRateLimit } from '../_lib/withUserRateLimit';
import { createRateLimiter } from '@acme/security';

Step 3: Add Request Validation

Use Zod for schema validation:

import { z } from 'zod';

const RequestSchema = z.object({
  field: z.string().min(1),
});

Step 4: Create Integration Test

Path: packages/tests/src/{feature}.test.ts

See templates.md for test template.

Step 5: Verify

Run these commands:

1. pnpm typecheck - Type check
2. pnpm lint - Lint check
3. pnpm test:integration - Run tests

Checklist

• Route file created at correct path
• Authentication check using getCurrentUser()
• Rate limiting applied via withUserRateLimit
• Request validation with Zod
• Proper error responses (400, 401, 403, 429, 500)
• Integration test created
• TypeScript types pass
• ESLint passes

Guardrails

• ALWAYS use getCurrentUser() from @acme/auth for auth
• ALWAYS apply rate limiting to user-facing endpoints
• NEVER expose internal errors to clients
• NEVER skip request validation
• If unsure about rate limit config, ask user