---
name: api-contracts
description: Specify API contracts for all system interfaces
summary: "Specifies every API endpoint — request/response shapes, error codes with human-readable messages, auth requirements, pagination, and example payloads — so frontend and backend can be built in parallel."
phase: "specification"
order: 830
dependencies: [review-architecture]
outputs: [docs/api-contracts.md]
conditional: "if-needed"
knowledge-base: [api-design]
---

## Purpose
Define API contracts for all system interfaces — REST endpoints, GraphQL schema,
WebSocket events, or inter-service communication. Each endpoint specifies request/
response shapes, error codes, authentication requirements, and rate limits.
Contracts serve as the definitive agreement between frontend and backend agents,
enabling parallel development with confidence.

## Inputs
- docs/system-architecture.md (required) — component interfaces to specify
- docs/domain-models/ (required) — domain operations to expose
- docs/adrs/ (required) — API style decisions (REST vs GraphQL, versioning)

## Expected Outputs
- docs/api-contracts.md — API specification with endpoints, request/response
  shapes, error contracts, auth requirements

## Quality Criteria
- (mvp) Every domain operation that crosses a component boundary maps to >= 1 API endpoint
- (mvp) If domain-models/ does not exist, API boundaries derived from user story acceptance criteria
- (mvp) Every endpoint documents: success response code, error response codes, error response body schema, and at least 2 domain-specific error codes per endpoint with human-readable reason phrases (e.g., 400 `invalid_email`, 409 `user_already_exists`)
- (mvp) Authentication and authorization requirements per endpoint
- (deep) Versioning strategy documented (if applicable)
- (deep) Pagination, filtering, and sorting for list endpoints
- (deep) Idempotency documented for mutating operations
- (deep) Pagination schema documented for all list endpoints (cursor or offset, page size limits, total count)
- (mvp) Example request and response payloads included for each endpoint
- (mvp) Every API endpoint from system-architecture.md is specified

## Methodology Scaling
- **deep**: OpenAPI-style specification. Full request/response schemas with
  examples. Error catalog. Auth flow diagrams. Rate limiting strategy.
  SDK generation considerations.
- **mvp**: Endpoint list with HTTP methods and brief descriptions. Key
  request/response shapes. Auth approach.
- **custom:depth(1-5)**:
  - Depth 1: endpoint list with HTTP methods and brief descriptions.
  - Depth 2: endpoint list with key request/response shapes and auth approach.
  - Depth 3: add full schemas, error contracts with domain-specific codes, and example payloads.
  - Depth 4: full OpenAPI-style spec with rate limiting, pagination, and idempotency documentation.
  - Depth 5: full spec with SDK generation considerations, versioning strategy, and auth flow diagrams.

## Mode Detection
Check for docs/api-contracts.md. If it exists, operate in update mode: read
existing endpoint definitions and diff against current system architecture and
domain models. Preserve existing endpoint paths, request/response schemas, and
error contracts. Add new endpoints for new features or domain operations.
Update error contracts if domain model changed validation rules. Never remove
or rename existing endpoints without explicit user approval.

## Update Mode Specifics
- **Detect prior artifact**: docs/api-contracts.md exists
- **Preserve**: existing endpoint paths, HTTP methods, request/response schemas,
  error codes, auth requirements, pagination patterns, versioning strategy
- **Triggers for update**: architecture changed component boundaries, domain
  models added new operations, ADRs changed API style or auth approach
- **Conflict resolution**: if architecture moved an operation to a different
  component, update the endpoint's component ownership but preserve its contract;
  flag breaking schema changes for user review