# Haven API

Haven is a direct-booking and property management platform for short-term rentals. Hosts manage listings, calendars, rates, reservations and guest messaging here, and this API is how software you build reaches that data on a host's behalf.

The API is read and write. An integration can pull a portfolio's listings and calendar, push availability blocks and rate overrides, read and respond to guest messages, and act on reservations. It reaches the same code paths the Haven web dashboard and the Haven mobile app use, so a write made through the API fans out exactly as it would if the host had made it themselves: channel manager push, guest email and SMS, pricing sync.

## What makes this API different

Authorization is granular. Most platforms in this category offer a single key with two settings, read or write, across everything the account owns. Haven declares 24 requestable scopes, and a host consents to a named list rather than to a category. A pricing tool that asks for `rates:read` and `rates:write` gets exactly that, and cannot read a guest's email address or cancel a stay.

Access is reviewed. There is no self-serve key. You apply, Haven reviews the application, and staff set the maximum scope set your application may ever request. Until that happens your client exists but authorizes nothing. Use of the API is governed by the [Developer and API Terms](/terms/developer-terms).

Failures explain themselves. A 403 names the scope you were missing and returns a link that re-runs authorization with it included. A 429 names which limit you hit and when it resets.

## Where to start

Read [Getting access](00-start-here/01-getting-access.md) first. It covers the application, what Haven looks for, and how sandbox credentials work, and you can build the entire integration against sandbox before anyone reviews you.

[Quickstart](00-start-here/02-quickstart.md) walks the shortest path from credentials to an authenticated call.

[How it fits together](00-start-here/03-how-it-fits-together.md) explains Haven's data model in the terms the API uses, which is worth twenty minutes before you design anything.

## Status

The authorization server, the resource endpoints and webhooks are in active development against the specification published here. This documentation describes the contract they implement. Pages that describe an endpoint you cannot yet call say so at the top.

The scope registry, the error taxonomy, the identity model and the approval process are built and are stable. What is documented on those pages is what the server does today.

## Guidebook widgets

Hosts can place a link, a sandboxed embed of your web app, or a Haven-rendered action button on a listing's guidebook.

- [Verifying `haven_ctx`](08-guidebook-widgets/01-haven-ctx.md) — short-lived guest token on embed URLs
- [Action webhooks](08-guidebook-widgets/02-action-webhooks.md) — `X-Haven-Signature` on outbound POSTs

These use the per-widget `whsec_…` secret from the listing editor, not a public-API OAuth credential.

## Getting help

Write to info@bookwithhaven.com. Include the correlation id from the response header of the call you are asking about; it identifies the exact request in Haven's logs and turns most questions into a two-minute answer.