# Public API compatibility policy

The RentEngine public API is versioned by URL prefix: `/api/public/v1`.

## What we will not break on `/v1`

- Existing paths, method semantics, and required request fields
- JSON field names and types already documented for a given operation
- Auth: `Authorization: Bearer <token>`
- Error response shape `{ "error": string, ... }` (Bearer JSON errors for mapped statuses also send `code`)
- Default list response type: a JSON array stays an array (we will not wrap it in `{ data, page }` on `/v1`)

## What we may add without a new version

- New endpoints and new optional query/body fields
- New optional response fields (`code` on Bearer error JSON)
- New response headers (`X-Has-More`, `X-Next-Page-Number`, `X-Request-Id`)
- New optional request headers (`Idempotency-Key`)
- New webhook event types

Clients should ignore unknown fields and headers.

## Breaking changes

A change that removes a field, changes a documented type, or changes default
behavior ships under a new path prefix (`/api/public/v2`, …).

A breaking change to — or removal of — an existing production endpoint is
announced at least 30 days in advance. Nothing else carries an advance-notice
commitment.

## Changelog

See [CHANGELOG.md](https://app.rentengine.io/openApi/api/public/v1/CHANGELOG.md).