# 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:

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

Validation errors remain FastAPI's standard `422` validation response.