# Changelog

Changes to the public API, newest first.

Additive changes ship without notice. Breaking changes are announced here, carry `Deprecation` and `Sunset` headers on affected responses, and are emailed to every application's security contact.

## What counts as breaking

Removing an endpoint, a field or an operation. Changing a field's type. Making an optional request field required. Removing a value from a closed enumeration. Narrowing what a scope grants.

## What does not

Adding an endpoint, an optional field, an operation, a scope, a webhook event, or a value to an open enumeration. Reordering fields. Rewording an `error.message`.

**Your client must tolerate all of these.** Ignore unknown fields, ignore unknown webhook event types rather than rejecting them, and never switch exhaustively over a value the API returns unless it is documented as closed. Adding a booking status should not break your integration, and if it would, that is a bug worth fixing before it costs you an outage.

## Versioning

The major version is in the path: `/api/public/v1`. It changes only for a change that cannot be made additively, and v1 will keep working alongside any successor for a published period rather than being switched off.

Every response carries `X-Haven-Api-Version`.

---

## Unreleased

Everything below is built. Nothing here is callable in production until Haven finishes provisioning and approves your application — see [Getting access](../00-start-here/01-getting-access.md).

- **Guidebook widgets** (link / embed / action cards). Embed apps verify [`haven_ctx`](../08-guidebook-widgets/01-haven-ctx.md). Action endpoints verify [`X-Haven-Signature`](../08-guidebook-widgets/02-action-webhooks.md). `GET /properties/{code}/guidebook` now includes additive `customPages` (`kind`, `title`, `url` for LINK only).

Callable:

- **Blog site and listing import.** The consent screen asks the host which site a `blog:write` connection is for, and `GET /me` returns it as `site`. New read `GET /property-groups/{code}`: the collection's logo, contact, social profiles, author, target cities, cities and neighborhoods. `GET /properties/{code}` adds `url`, `updatedAt`, `photos` (every photo, with alt text and tag), `location` (street address and coordinates), `descriptions`, `amenities`, `brand` and `author`; `GET /properties` adds `url` and `updatedAt`. `listings:read` now covers the street address. `upsert_blog_post` accepts `authorPhotoUrl`, and the first published delivery adds a Blog page to a site that has none. See [Blog publishing](../04-api/05-blog-publishing.md).
- **Blog publishing.** Two scopes, `blog:read` and `blog:write`; two operations, `upsert_blog_post` and `unpublish_blog_post`; and two reads, `GET /blog-posts` and `GET /property-groups`. An article sent as published goes live on the named sites, styling never crosses the boundary, and images are copied to Haven's CDN. See [Blog publishing](../04-api/05-blog-publishing.md).
- **The OAuth 2.1 authorization server.** Both discovery documents, `/oauth/authorize` with the host consent screen, and `/api/public/oauth/token`, `/revoke` and `/introspect`. PKCE with `S256` is mandatory for every client, confidential ones included. Refresh tokens rotate, with a sixty-second grace window for concurrent refreshes.
- **The resource endpoints** under `/api/public/v1`. Twenty-one reads.
- **The write surface.** `POST /operations/{operation}` and the `GET /operations` catalogue, thirty-two operations. `issue_booking_refund` and `adjust_booking_price` are two-step: the first call is refused and returns a confirmation token.
- **The [MCP endpoint](../04-api/04-mcp.md)** at `/api/public/mcp`. Every read and every write operation as a Model Context Protocol tool, plus a `search`/`fetch` pair, dispatched through the same code as the REST request — same scopes, same limits, same idempotency ledger.
- **`/connected-apps`**, where a host reviews and revokes the applications connected to their account.
- The scope registry. The [Scope reference](../02-scopes/02-scope-reference.md) is generated from the registry the server enforces.
- The error taxonomy, including `insufficient_scope` with the missing scope named.
- The approval gate. No credential functions until Haven staff move an application to `SANDBOX` or `APPROVED`.

Not yet callable:

- **Webhook delivery.** Planned for v1.1; the [Webhooks](../05-webhooks/01-overview.md) pages describe the design rather than a live surface. Until it ships, poll with `updated_since`.
- **The developer console.** Applications are handled by email in the interim.

## 2026-08-31

Public API documentation published, separated from Haven's first-party mobile API documentation.