# API Endpoint Scaffold

> Scaffold new Next.js API endpoints with authentication, rate limiting, and tests. Use when creating new API routes, adding endpoints, or building API features. Use when this capability is needed.

- Skill: `tomevault-io/api-endpoint-scaffold` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/api-endpoint-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/api-endpoint-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/api-endpoint-scaffold

---


# 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](./templates.md).

### Step 2: Add Rate Limiting (if needed)

Import from existing pattern:

```typescript
import { createRateLimiter } from '@acme/security';
import { withRateLimit } from '../_lib/withRateLimit';
```

### Step 3: Add Request Validation

Use Zod for schema validation:

```typescript
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](./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()` inside the handler
- [ ] Rate limiting applied via `withRateLimit`
- [ ] 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 inside the handler function
- ALWAYS apply rate limiting to user-facing endpoints via `withRateLimit`
- NEVER expose internal errors to clients
- NEVER skip request validation
- If unsure about rate limit config, ask user

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jamesjlundin) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->