---
name: api-endpoint
description: Scaffold a new REST API endpoint with input validation (Zod), error handling, types, and basic test.
disable-model-invocation: true
argument-hint: "[resource-name]"
context: fork
agent: backend-architect
---

# Scaffold API Endpoint

Create a production-ready API endpoint for resource `$ARGUMENTS`.

## Steps

1. **Read project context first:**
   - Check `docs/backend/architecture.md` for module structure
   - Check `docs/backend/api-design.md` for conventions (naming, pagination, errors)
   - Check `RECOMMENDATIONS.md` for locked stack (framework, ORM, validation)
   - Look at existing endpoints in `apps/api/` for patterns

2. **Create endpoint with:**
   - RESTful routes: `GET /`, `GET /:id`, `POST /`, `PATCH /:id`, `DELETE /:id` (only applicable ones)
   - Zod schemas for request validation (params, query, body)
   - TypeScript types derived from Zod schemas
   - Consistent error responses: `{ error: string, code: string, details?: unknown }`
   - Pagination for list endpoints (`cursor` or `offset/limit`)
   - Proper HTTP status codes (200, 201, 400, 404, 422, 500)

3. **Security considerations:**
   - Input validation before processing
   - No SQL/NoSQL injection (parameterized queries)
   - Auth middleware placeholder (if applicable)
   - Rate limiting note (if public endpoint)

4. **Files to create:**
   - Route handler / controller
   - Zod validation schemas
   - Types file (if separate)
   - Basic integration test

5. **Output:** working code following project conventions. Note any assumptions made.