API Contract - Typed Frontend/Backend Contracts

Ensures every API endpoint has a typed contract: Pydantic models on the backend, Zod response schemas on the frontend, and documented error responses. Bridges the gap between apps/backend/src/api/ and apps/web/lib/api/.

Description

Enforces type-safe API contracts across the FastAPI backend and Next.js frontend. Every endpoint must declare a Pydantic response_model, have a matching Zod schema on the frontend, and document error responses via OpenAPI. Prevents schema drift, untyped responses, and manual type definitions by mandating a single source of truth through the Contract Triangle pattern.

When to Apply

Positive Triggers

• Creating or modifying API endpoints (FastAPI routes)
• Adding frontend API calls (apiClient.get/post/put/patch/delete)
• Reviewing type safety between backend responses and frontend consumers
• Documenting API error responses
• Planning API versioning or deprecation
• User mentions: "API contract", "endpoint", "response type", "OpenAPI", "schema"