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

Additive, backwards-compatible changes may ship inside v1 (new optional JSON fields, docs clarifications).
Breaking changes require a new path version (/api/v2/...) and an updated OpenAPI info.version.
When a version is deprecated, responses for that version will include a Deprecation header and a Sunset HTTP-date for the planned removal. Docs on this page will state the date in plain language first.
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.

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.

More reading: Docs, versioning.md, auth.md, GitHub.