# Property Bot API versioning policy

Canonical public routes live under **URL path versioning**: `/api/v1/*`. Unversioned `/api/health` and `/api/info` are stable aliases of the same v1 payloads. Markdown twins (`/api/v1/info.md`, `/api/info.md`, and the health equivalents) describe the same surface as `text/markdown`.

## Current status

- **Current version:** v1
- **Sunset:** none. **v1 has no sunset date** and is not deprecated.
- **Deprecation headers:** this origin does **not** send `Deprecation` or `Sunset` response headers today, because nothing on the public surface is deprecated or scheduled for removal. We will not invent imminent sunset headers.

## Compatibility rules

1. Additive, backwards-compatible changes may ship inside v1 (new optional JSON fields, docs clarifications).
2. Breaking changes require a new path version (`/api/v2/...`) and an updated OpenAPI `info.version`.
3. When a version is deprecated, responses for that version will include a `Deprecation` header (RFC 9745 / draft practice) and a `Sunset` HTTP-date for the planned removal. Docs on this page will state the date in plain language first.
4. Unversioned `/api/health` and `/api/info` track the latest stable major (today: v1). If a future major becomes current, aliases either keep serving the prior major until Sunset or redirect — documented here before any change.

## Errors

Unknown `/api/*` paths and disallowed methods return `application/json` shaped as `{"error":{"code","message","hint"}}` (OpenAPI `ErrorResponse`). See [/openapi.json](https://property.bot/openapi.json).

## What this policy covers

Public REST only: health and info (plus `.md` twins). Bearer-gated MCP at https://mcp.property.bot/mcp is a separate surface and is not versioned by these `/api/v1` paths.