Changelog

This page tracks changes to the public /v1 API.

Additive only

Within a version, changes are additive only — new fields, new endpoints, never a renamed or removed one. A breaking change means a new version (/v2), not a change to /v1.

Unreleased

2026-11-03: Sign in with email and password only

A person now has one identity and one password across all workspaces. Login finds the workspaces from the email. These changes affect the dashboard session routes (/v1/auth/*, /v1/users). The tenantId and tenantSlug fields are still accepted, so old callers keep working.

• POST /v1/auth/login takes { email, password }. tenantId or tenantSlug is now optional. It is a preferred workspace. Send at most one. Sending both returns 400 validation_failed. A workspace the person does not belong to is ignored. It is not an error.
• POST /v1/auth/login now returns 200 with a status field:
  • signed_in: { status, user, accessTokenExpiresAt, workspace }, and the session cookies are set. Before, the body had no status and no workspace.
  • choose_workspace: { status, workspaces: [{ tenantId, slug, name, role }] }. No session exists yet. The response sets a be_ws_select cookie that lasts 5 minutes.
  • A wrong password, an unknown email, and a locked account still return 401 invalid_credentials.
• New: GET /v1/auth/workspace-choices returns the workspaces for the be_ws_select cookie.
• New: POST /v1/auth/select-workspace with { tenantId } returns the signed_in body and sets the session cookies. A missing or expired cookie, or a tenantId the person does not belong to, returns 401 invalid_workspace_selection.
• POST /v1/auth/password-reset/request takes { email }. The tenant is optional. The reset link still carries the workspace. POST /v1/auth/password-reset/confirm is unchanged and still needs tenantId or tenantSlug. A new password applies to all the person’s workspaces and ends their sessions in all of them.
• Rate limits: the password-reset request limit of 3 per 15 minutes now counts per email, not per workspace and email. The sign-in lockout counts per person and per IP address, across workspaces. See Rate limits.
• POST /v1/users and POST /v1/users/invite return { userId, email, role }. They no longer return the invite token. The invitee gets an email. If the server cannot build a working link, the call returns 503 invites_unavailable and saves nothing. A new member shows as invited until their first login to that workspace, then as active.

See Signing in and Errors.

Channel manager and equipment rental are switched off

Two parts of the API are off on the current deployment (ADR-0020). Their routes still exist and answer 503. Nothing is stored or sent.

• Channel manager: /v1/channel-connections (and its credentials and listings calls), /v1/channel/conflicts, the iCal feed-token calls /v1/resources/{id}/feed-tokens, and GET /v1/feeds/{token}.ics answer 503 with the code channel_unavailable. iCal import and the Booking.com and Agoda connections do not run.
• Equipment rental: POST /v1/quotes/rental and GET/PUT /v1/rate-plans/{id}/rental-tiers answer 503 with the code rental_unavailable. The widget’s data-mode="rental" still starts, but its first quote fails.

The sections below that describe these features show what the API was built to do. They are not available yet. See Errors.

Outbound webhooks

You can now receive signed webhooks. All changes are additive:

• GET/POST /v1/webhook-endpoints and DELETE /v1/webhook-endpoints/{id} (sk_ with webhooks:manage). The signing secret (whsec_…) is shown once.
• We send reservation.created, reservation.confirmed, reservation.cancelled, payment.succeeded, payment.failed, and refund.created.
• Each delivery is signed with HMAC-SHA256 in the X-Booking-Signature header. The event name is in X-Booking-Event-Type and the delivery id is in X-Booking-Event-Id.
• The endpoint url must be https:// on a public host. http://, localhost, and private IP addresses return 400 validation_failed. We do not follow redirects; a 3xx counts as a failed try.
• A failed delivery is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, and 12 hours. We check for due retries once a minute.

See Webhooks.

Sign in with a workspace name (replaced by the 2026-11-03 change above)

POST /v1/auth/login, POST /v1/auth/password-reset/request, and POST /v1/auth/password-reset/confirm now accept tenantSlug (the short workspace name, for example demo) instead of tenantId. Send exactly one of the two. Sending both, or neither, returns 400 validation_failed. An unknown workspace looks the same as an unknown account: login returns 401 invalid_credentials. All changes are additive.

New limits and headers

All changes are additive, but a caller that was fast enough to hit one will see a new 429 or 413:

• Sign-in is limited to 20 requests per minute per IP address. Password-reset requests are limited to 10 per 15 minutes per IP address and 3 per 15 minutes per email. Password-reset confirms are limited to 10 per 15 minutes per IP address. Each returns 429 rate_limited with Retry-After.
• POST /v1/holds with a pk_ key is limited to 2 active holds per key and IP address, and 50 active holds per tenant. Over a cap returns 429 active_hold_limit_reached with Retry-After. sk_ keys are exempt.
• The hold-creation rate limit (10 per minute) is now counted per key and IP address, not per IP address alone.
• Retry-After is now readable from browser code on cross-origin responses (Access-Control-Expose-Headers: Retry-After).
• A request body larger than 64 KB returns 413 payload_too_large. The Stripe webhook allows 256 KB.

See Rate limits.

Booking confirmed email

The guest now gets a “Booking confirmed” email when a booking becomes confirmed: after a Stripe payment, after a guest confirm, or after an operator confirms it as paid offline. The email goes to the guest’s email address, so a booking with no guest email (an OTA booking) gets none. A repeated confirm does not send a second email.

Widget script API and hourly flow

• The booking widget script is https://docs.booking-engine.davidvalentino.com/widget/v1.js. Set data-api-base to your API host. Without it, the widget calls the host of its own script.
• The script adds window.BookingWidget with mount(el, options), which returns { destroy() }, and scan(root). You can mount from React, Vue, Svelte, and other code. See Embed the widget.
• For an hourly space, the widget asks for the length, the day, the start time, and the number of people. It then asks for the guest’s name, email, and optional phone before it holds the time and sends the guest to pay.

Guest contact on holds

POST /v1/holds now accepts an optional guest object, so you can reach a guest who pays you offline. All changes are additive:

• guest: { "name": "1-120 chars", "email": "valid email, up to 254 chars", "phone": "optional, 6-20 chars, digits and spaces, optional leading +" }. The email is trimmed and made lowercase.
• With a pk_ key, guest is required for hourly spaces. Without it the call returns 400 with the new code guest_required. It stays optional for hotels and for sk_ keys, so existing calls keep working.
• The contact is saved on the booking. Every booking response (GET /v1/bookings, GET /v1/bookings/{id} and the other /v1/bookings calls) returns it as guestEmail, guestName and guestPhone, each null when not given. No response to a pk_ key ever returns it.
• The Stripe checkout page now shows the guest’s email already filled in.

Confirm a booking that was paid offline

New endpoint POST /v1/bookings/{id}/confirm. Use it when a guest booked through the widget but pays you in cash or by bank transfer. Without it, the hold expires after 15 minutes. All changes are additive:

• Body: { "paidOffline": true, "note": "optional, up to 500 characters" }. It returns 200 with the booking, now confirmed. Send the same call again and you get 200 again, with no second event.
• It needs an sk_ key with bookings:write, or a tenant_admin dashboard session. A pk_ key gets 404.
• It only works on a held booking whose hold has not expired. Otherwise it returns 409 with the new code not_confirmable. The detail text names the current state. A booking that was already confirmed by an online payment also returns 409.
• A reservation.confirmed webhook is sent. The note is kept in the audit trail only.
• The 409 unavailable text for quotes and bookings now reads “This time is not available.” (it said “The requested stay…”). The code is unchanged.

Hourly spaces and services

You can now sell time by the hour: meeting rooms, desks, studios, and services. The new guide Hourly spaces and services walks through slots, quote, hold, and checkout. What changed, all additive:

• New endpoint GET /v1/resources/{id}/slots?date&duration&party_size. It works with pk_ keys and returns the bookable start times for one local date.
• POST /v1/quotes works for an hourly space (leave ratePlanId out). It refuses a window that is not one of the slots: 409 unavailable, or 400 invalid_duration if the length is not an allowed duration.
• availability reasons gain outside_opening_hours, min_notice, max_advance, and buffer_conflict.
• priceBreakdown gains unit (night, hour, or slot) and lines[]. Hotel quotes keep nights[] exactly as before and also fill lines[]. nights[] is deprecated and is removed only in a new API version.
• A resource now has vertical (lodging, equipment, or hourly), timezone, and slotConfig (hourly only). POST /v1/resources accepts vertical, timezone, pricing, and slotRules. New PATCH /v1/resources/{id}.
• Setup endpoints for operators (sk_ with resources:write, or a dashboard session): GET/PUT /v1/resources/{id}/slot-rules, GET/PUT /v1/resources/{id}/hourly-pricing, GET/PUT /v1/resources/{id}/opening-hours. Tenant hours are GET/PUT /v1/tenant/opening-hours (dashboard session only).
• The tenant profile gains defaultVertical.
• New error codes: invalid_hours, invalid_duration, not_hourly, invalid_timezone, invalid_resource.

Date range limits on availability and quotes

GET /v1/availability now accepts at most 92 nights per call, and POST /v1/quotes at most 366 nights. A longer window returns 400 validation_failed.

Allowlists for API keys

A secret (sk_) key can now be locked to a list of IP addresses and CIDR ranges. A request from any other address gets 404 with the code ip_not_allowed. Keys with no list work as before.

For a publishable (pk_) key, origin matching now ignores case and default ports, and an entry like https://*.example.com allows any subdomain (not the apex). Operators can edit both lists on a live key with PATCH /v1/api-keys/{id}, so the key does not need to be reissued. See Authentication.

Calendar: pk_ keys work again; guest details need bookings:read

GET /v1/resources/{id}/calendar accepts pk_ keys again, so the embeddable calendar works. A pk_ key gets availability, price hints, and restrictions, never guest details. On an sk_ key, the occupants field now needs bookings:read; with only availability:read it is omitted.

Automatic refund when a payment arrives after the hold expired

If a guest pays after their hold has already expired or been cancelled, the payment is now refunded in full automatically, and a refund.created webhook is sent. A booking that was ever confirmed is never refunded automatically.

Calendar window is now at most 92 nights

GET /v1/resources/{id}/calendar now accepts at most 92 nights per call (it was 366). A longer window returns 400 range_too_large. The response also no longer carries an ETag, so If-None-Match never returns 304.

Scope now required on four write routes

PUT /v1/resources/{id}/rates now needs rates:write. PUT /v1/resources/{id}/restrictions now needs restrictions:write. POST /v1/resources and POST /v1/room-types now need resources:write. Before, any secret key could call them, whatever its scopes. This was a security fix. A key without the scope now gets 404 insufficient_scope. Ask your operator to issue a key with the scope. See Secret key scopes.

Live today:

• GET /v1/ping — liveness check.
• GET /v1/availability — resource availability by date range and party size.
• GET /v1/resources, GET /v1/resources/{id} — resource, room-type, and rate-plan read.
• GET/PUT /v1/resources/{id}/rates, GET/PUT /v1/resources/{id}/restrictions — rate and restriction management.
• POST /v1/rates/bulk — set a nightly rate and/or a restriction across a date range for many resources of the same room type in one call (sk_ only).
• GET /v1/metrics/summary — revenue and occupancy for a date range, defaulting to the current calendar month (sk_ and an operator session only — it’s money, so pk_ can never call it). Powers the dashboard’s Today screen.
• GET /v1/resources/{id}/calendar — per-day availability, price hint, and restrictions over a date range. See Calendar and iCal feeds.
• GET /v1/feeds/{token}.ics and the feed-token endpoints (/v1/resources/{id}/feed-tokens) — iCal export of confirmed bookings and synced external blocks. Not available yet: these answer 503 channel_unavailable. See Calendar and iCal feeds.
• iCal import — pulling an OTA’s calendar in as external blocks. Not available yet: it does not run.
• GET /v1/resources/{id}/slots — bookable start times of an hourly space for one local date and one duration (sk_, pk_, and operator session). See Hourly spaces and services.
• POST /v1/quotes — priced, signed, 15-minute quotes.
• POST /v1/holds/{id}/otp, POST /v1/holds/{id}/otp/verify — guest email verification.
• POST /v1/holds, POST /v1/holds/{id}/confirm — hold creation and confirmation. Confirming a hold requires a succeeded card payment — see Holds and confirmation.
• POST /v1/holds/{id}/payment-intent — creates a Stripe PaymentIntent for a held reservation, for a server-side integration using Stripe.js or Stripe Elements directly (sk_ only).
• POST /v1/holds/{id}/checkout-session — creates a Stripe-hosted Checkout Session for a held reservation and returns a redirect URL (sk_ and pk_); this is what the embeddable widget uses to take payment.
• Card payment (Stripe) is live: both the server-side PaymentIntent flow and the widget’s hosted-checkout flow confirm a reservation automatically once Stripe reports a succeeded payment.
• GET /v1/bookings — a cursor-paginated list of bookings (sk_ with bookings:read, or an operator session).
• GET/PATCH/DELETE /v1/bookings/{id} — booking read, transition, and cancellation (sk_ only).
• POST /v1/bookings — an operator creates a booking. Send Idempotency-Key. With paidOffline: true the booking is confirmed at once. Without it, the booking is held and the response carries a Stripe checkoutUrl to send to the guest (sk_ with bookings:write, or an operator session).
• GET/POST /v1/webhook-endpoints, DELETE /v1/webhook-endpoints/{id} — outbound webhooks. See Webhooks.
• POST /v1/bookings/{id}/refunds — full or partial refund of a booking’s succeeded payment (sk_ with payment:refund:create, or an operator session — never pk_, the same “no money” rule as everywhere else). See Refund a booking.
• The embeddable widget — a full booking flow: availability, quote, hold, and payment through a Stripe-hosted checkout page. See Embed the widget. A live demo runs at /widget-demo/.
• The embeddable availability calendar — a separate, smaller, read-only widget: availability and a per-night price hint for one resource, no booking flow, pk_-authed, no PII. See Embed the calendar. A live demo runs at /calendar-demo/.
• The dashboard’s Today screen now leads with a revenue, occupancy, and bookings-this-month summary, alongside Payments, API Keys, the widget configurator (which now generates both the booking widget’s snippet and the calendar embed’s), and Settings — all live for operators.

Channels (Booking.com, Agoda, iCal)

Not available yet

Every route in this section answers 503 channel_unavailable. The list below shows what was built. It does not work on the current deployment.

• GET/POST /v1/channel-connections, DELETE /v1/channel-connections/{id} — configure a channel. POST is discriminated on channel: ical takes a feedUrl, booking_com a hotelCode, agoda a list of propertyIds. An OTA connection is created pending and activates once credentials are stored.
• PUT /v1/channel-connections/{id}/credentials — store or rotate an OTA client id + secret. Write-only by design: the secret is encrypted at rest and the response contains only a summary (client id, key version, last updated). There is no endpoint that returns it, and there will not be one. Returns 503 if the deployment has no encryption key configured, rather than storing the secret in plaintext.
• GET/POST /v1/channel-connections/{id}/listings, PATCH /v1/channel-connections/{id}/listings/{listingId} — map one of your resources to the channel’s own property / room-type / rate-plan ids. A resource with no mapping is invisible to that channel; nothing is ever guessed for you.
• GET/PATCH /v1/channel/conflicts — the double-booking queue and its resolution.

All channel endpoints are sk_ or operator-session only. A publishable (pk_) key can never call them — this is inventory and credential surface.

Equipment rental

Not available yet

POST /v1/quotes/rental and GET/PUT /v1/rate-plans/{id}/rental-tiers answer 503 rental_unavailable. A hold cannot be made from a rental quote. The list below shows what was built. It does not work on the current deployment.

A rental vertical layered on the same resource model — daily/weekly/monthly tiered pricing and allocating one of several interchangeable units instead of one specific room. See Rent out equipment through the API.

• POST /v1/room-types — create a room type; vertical: "equipment" makes it a rental model. GET /v1/room-types lists your models (cursor-paginated, optional ?vertical= filter) — including ones created before you’ve added units. POST /v1/resources — add a physical unit under a room type. All sk_ or operator-session only.
• GET/PUT /v1/rate-plans/{id}/rental-tiers — read and set the daily / weekly / monthly price tiers on a rate plan. A longer tier may never cost more per day than a shorter one (422 invalid_tiers).
• POST /v1/quotes/rental — a priced, signed rental quote over a whole-day date range, quoted against the room type (the engine picks the cheapest whole-block cover of the duration and reports the free-unit count). Separate from the lodging POST /v1/quotes.
• POST /v1/holds gains an optional, rental-only delivery object (address required; deliveryAt/collectionAt informational). The engine allocates a free unit at hold time; 409 no_unit_available if the fleet sold out between quote and hold.
• The embeddable widget has a rental mode (data-mode="rental") — a date-range picker over the tiered price with an optional delivery field.
• The operator dashboard has an Equipment inventory screen for setting all of this up without the API.

Payment is still the same one-time full charge as lodging. A refundable security/damage deposit and recurring billing for long rentals are not shipped — see the caution in the guide.

Not yet released

The channel manager (iCal, Booking.com, Agoda) and equipment rental are switched off — see the first note under Unreleased. Also not released: the generated SDK’s public registry publish, a resource/rate-plan picker inside the widget, and the reservation.created and payment.failed webhook events (you can subscribe to them, but we do not send them).

This changelog starts recording dated entries once the API reaches its first tagged release.