repo-scoping/docs/api-contract.md

API Contract Policy

The public HTTP API is currently version 0.1.0. Until a versioned path such as /api/v1 is introduced, compatibility is governed by the OpenAPI contract published at /openapi.json and covered by the test suite.

Agent-facing endpoints are considered stable when their path, method, tag, and success response model appear in the OpenAPI contract snapshot test. A change to one of those fields is allowed, but it must update the snapshot test in the same change so the break is explicit during review.

Compatible changes include:

• adding optional request fields with defaults
• adding response fields that clients may ignore
• adding new endpoints
• adding new examples or descriptions

Breaking changes include:

• removing or renaming an endpoint
• changing an endpoint method or tag
• changing the success response model
• removing or renaming a response field
• making an optional request field required
• changing the shape of common error responses

Common application errors use:

{"detail": "repository 999 was not found"}

Validation errors remain FastAPI's standard 422 validation response.