# Git Brain public discovery API policy

Git Brain's supported public HTTP surface is limited to the agent-discovery resources described by [`/openapi.json`](/openapi.json). Git Brain does not currently offer a supported third-party product REST API.

## Versioning

The current discovery API major version is `1`.

- Clients may send `Git-Brain-API-Version: 1` on discovery requests. Omitting the header currently selects version 1.
- Every discovery response includes `Git-Brain-API-Version: 1`.
- An unsupported requested version receives a structured JSON `400` response with the stable error code `UNSUPPORTED_API_VERSION`.
- Backward-compatible fields and resources may be added within version 1. A breaking contract change will use a new major version.

## Deprecation and sunset

No version or operation is currently deprecated.

When Git Brain deprecates an operation or version, affected responses will include the [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) `Deprecation` header and a `Link` with `rel="deprecation"` pointing to migration guidance. Git Brain will normally provide at least 180 days' notice before removal. When a removal date is scheduled, affected responses will also include the [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) `Sunset` header. Removed resources return `410 Gone` with a structured recovery hint.

## Rate limits

Public discovery traffic has a soft limit of 600 requests per 60-second window for each client and edge partition. Responses expose the current IETF HTTPAPI draft fields:

- `RateLimit-Policy: "public-discovery";q=600;w=60`
- `RateLimit: "public-discovery";r=<remaining>;t=<seconds-until-reset>`

For clients that implement the earlier field names, responses also include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. A request that exceeds the available quota receives `429 Too Many Requests`, a structured JSON error, and `Retry-After` in seconds. The `Retry-After` value is never shorter than the reset interval in `RateLimit`.

Rate-limit state is enforced independently at each edge partition, so switching network paths can change the observed remaining quota. Clients should use the headers on the most recent non-cached response rather than assuming a global counter.

## Recovery resources

- [OpenAPI description](/openapi.json)
- [Concise agent context](/llms.txt)
- [Full agent context](/llms-full.txt)
- [Sitemap](/sitemap.xml)