API Contract

Overview

API Contract guides the creation of api-contract.md files that serve as the shared interface between backend and frontend agents during sprint execution. The contract defines request/response schemas, endpoint routes, TypeScript interfaces, and error formats so that implementation agents build to an agreed specification without direct coordination.

Prerequisites

• Sprint directory initialized at .claude/sprint/[N]/
• specs.md with defined feature scope and endpoint requirements
• Familiarity with RESTful API conventions (HTTP methods, status codes, JSON schemas)
• TypeScript knowledge for interface definitions (recommended)

Instructions

1. Create api-contract.md in the sprint directory (.claude/sprint/[N]/api-contract.md). Define each endpoint using the standard format: HTTP method, route path, description, request body, response body with status code, and error codes. See ${CLAUDE_SKILL_DIR}/references/writing-endpoints.md for the full template.
2. Define TypeScript interfaces for all request and response types. Use explicit types instead of any, mark optional fields with ?, and use string | null for nullable values. Reference ${CLAUDE_SKILL_DIR}/references/typescript-interfaces.md for canonical type patterns.
3. For list endpoints, include pagination parameters and the PaginatedResponse<T> wrapper. Standardize on page, limit, sort, and order query parameters as documented in ${CLAUDE_SKILL_DIR}/references/pagination.md.
4. Document all response states: success (200, 201, 204), client errors (400, 401, 403, 404, 422), and empty states. Use a consistent error response format with code, message, and optional details fields.
5. Follow best practices from : be specific about field constraints (e.g., "string, required, valid email format"), include request/response examples, reference shared types instead of duplicating, and omit implementation details (no database columns, framework names, or file paths).