Skip to main content

Changelog

All notable changes to the Booking Brain Developer API are documented here.

Documentation corrections — 2026-08-07​

Three errors in these docs meant an integration built by following them exactly could not make a successful call. All are now fixed:

Fixed​

  • Base URL corrected to /api/v1/developer. Earlier versions of these docs showed https://app.bookingbrain.com/api/v2/developer, which returns 404. There is no v2 — the working base URL is https://app.bookingbrain.com/api/v1/developer.
  • Public sandbox key removed. The previously published sandbox key (bb_sandbox_test_key...) was never provisioned and always returned 403. There is no sandbox key or sandbox mode: all keys are issued per-client by the Booking Brain team (see Authentication) and operate against live data, including real bookings and payments.
  • Search parameters corrected. The search endpoint rejects unknown parameters with a 422. Search examples previously used place, nights, pets, bedrooms, and sort, none of which exist on that endpoint (GET /developer/places/{slug} does accept nights). The correct names are property_place_slug, booking_nights, no_of_dogs, min_bed_rooms, and sort_by — see the API Reference for the full accepted list.
  • Example data corrected. Example property IDs and place slugs now reference real records (place slugs use the stay-in-* form, e.g. stay-in-exmoor); the previous examples (property 312, place exmoor) did not exist.

Admin API — 2026-06-22​

Admin-key READS that retire the DB tunnel for the property-closeout check. A property's security (damage) deposit, its assigned cancellation policy, and its discount levers / linked occupancy-group(s) can now be read over the API with an admin API key (or an admin/owner JWT) — no more dropping to the read-only database tunnel to confirm them. Each is read-only and ownership-guarded; the GET-before-write hard rules apply to the writes, not these reads. Ship with bb_app_api #1391 / #1392 / #1393 (#1382–#1386).

Added​

  • GET /properties/{id}/security-deposit — the refundable security/damage deposit + on/off flag ({ property_id, security_deposit, disable_security }). The read counterpart of PATCH /properties/{id}/security-deposit, and distinct from the payment deposit (GET /properties/{id}/deposit). Scope property.pricing:read. (#1382)
  • GET /properties/{id}/cancellation-policy — the property's assigned cancellation policy resolved against the public catalogue ({ cancellation_policy_ref_id, policy_title, owner_policy_description }). Distinct from bookings.cancellation-policy:read (the per-booking policy + cover) — this is the per-property assignment. New scope property.cancellation-policy:read. (#1383)
  • GET /properties/{id}/discounts/occupancy-groups — the shared occupancy-discount group(s) a property is linked to (the reverse lookup, complementing GET /occupancy-discounts/{id}). PII-free — the staff/owner name is stripped on the admin-API-key path. Scope property.pricing:read. (#1384)
  • GET /properties/{id}/discounts/low-occupancy and GET /properties/{id}/discounts/short-break-rules are now admin-API-key readable (were JWT-only). Scope property.pricing:read. (#1385)

Changed​

  • GET /properties/{id}/segment-pricing now also returns modified (ISO timestamp of the property's last change, for change-detection / cache-busting) and apply_price (the pricing-model flag: nightly / weekly / monthly / fixed). (#1386)
  • property.cancellation-policy:read added to the scope catalogue (admin docs) as a served read scope (low sensitivity) — the per-property analog of bookings.cancellation-policy:read.

Admin API — 2026-06-18​

Pricing/discount WRITES are now reachable with an admin API key, so a Read & write key carrying property.pricing:write (or an admin/owner JWT) can manage discounts and the shared occupancy-discount groups over the API — not just read them. The pricing hard rules (admin docs) (GET-before-write, Idempotency-Key, one property per run, verify) apply, and every endpoint also requires the caller to be an admin or the property's owner.

Added​

  • Occupancy-discount GROUPS (shared preset groups linked to many properties) — GET /occupancy-discounts/{id} (single read, admin-API-key callable; the key response is PII-free, omitting the staff user object), POST /occupancy-discounts, PUT /occupancy-discounts/{id} (replaces all of the group's date-window rows), DELETE /occupancy-discounts/{id}. The LIST — GET /occupancy-discounts — stays JWT-only (it embeds each group's owner name). Ships with bb_app_api #1352.
  • Per-property discount writes — POST/PUT/DELETE /properties/{id}/discounts/{low-occupancy|early-bird|late-availability|short-break-rules} and PATCH /properties/{id}/security-deposit (security/damage deposit only — distinct from the payment-deposit PUT /properties/{id}/deposit). Authorized for the admin API key in bb_app_api #1335.

Changed​

  • property.pricing:write moves from the roadmap to a served write scope in the scope catalogue (admin docs) — it now backs the discount/deposit/occupancy-group writes above (alongside the existing segment-pricing / pricing-model writes).

:::note Propagation Editing a shared occupancy-discount group does not currently bump the linked properties' price-propagation flag, so changes reach the OTA channels at the next daily price push. :::

Admin API — 2026-06-15​

Docs polish (review follow-up). Added required field lists to the bookings and channel-arrival-status 200-response schemas so generated clients and validators treat the always-present fields as guaranteed (nullable values stay nullable). No contract change.

Admin API — 2026-06-09​

Two new admin read endpoints so internal tooling can retire the read-only database tunnel. Both authenticate with an admin API key or an admin/owner JWT, and are scoped per property.

Added​

  • GET /properties/{id}/bookings — recent bookings for a property as a PII-free summary (dates, nights, party size, total price, the two discount amounts, channel and a cancellation flag). Filters: since/until (on the booking creation date, until inclusive), status, includeBlocks, limit, offset. Scope: bookings.recent:read.
  • GET /properties/{id}/channel-arrival-status — whether a property's changeover / arrival-day rule has reached the OTA channel feed (Airbnb / Booking.com via Rentals United): feed freshness, the arrival-open weekdays and the decoded changeover pattern. Scope: property.channel-status:read (new).

Neither endpoint returns guest PII; payment detail stays behind the audited bookings.payments:read scope.

Admin API — 2026-06-09​

Owner pricing-analysis reads are now reachable with an admin API key (scope property.pricing:read), so pricing reviews can run via the API instead of a database tunnel:

  • GET /properties/{id}/comparable-pricing — seasonal weekly-price percentiles across comparable properties
  • GET /properties/{id}/achieved-pricing — own realised weekly rates per season + a leap-year-aware BookingBrain occupancy figure
  • GET /properties/{id}/discounts, GET /properties/{id}/length-stay-discounts — discount levers

These join the existing segment-pricing / short-breaks / nightly-settings reads. The percentile maths was corrected to linear interpolation, and achieved-pricing gained medianWeekly + bbOccupancy. See Admin Data API → Pricing configuration (admin docs).

v2.0.0 — 2026-03-19​

:::caution Historical entry — contains errors This launch entry is preserved as originally published, but parts of it were never true: the API has always been served under /api/v1 (the "v2.0.0" label referred to the docs release, not the URL), and the sandbox key listed under Features was never provisioned — see the 2026-08-07 corrections above. :::

Initial public release of the Booking Brain Developer API.

Endpoints (22)​

  • Property Search — GET /search, GET /specialoffers
  • Property Details — GET /properties/{id}, GET /properties/slug/{slug}, GET /properties/{id}/extras, GET /properties/{id}/bedrooms, GET /properties/{id}/owner-contact, GET /properties/{id}/images, GET /properties/{id}/reviews, GET /properties/{id}/specialoffers
  • Availability & Pricing — GET /properties/{id}/unavailableDates, GET /properties/{id}/startDays, GET /properties/{id}/shortBreaks, GET /properties/{id}/start-dates, POST /properties/{id}/get-price, GET /properties/{id}/available-nights
  • Booking — POST /bookings/save, POST /bookings/validate-voucher
  • Payment — POST /bookings/processPayment
  • Places — GET /places, GET /places/{slug}
  • Usage — GET /usage/stats, GET /usage/logs

Features​

  • API key authentication via X-API-Key header
  • Sandbox key for development (bb_sandbox_test_key_do_not_use_in_production)
  • Per-minute rate limiting with X-RateLimit-* headers
  • IP whitelisting and origin restrictions for production keys
  • Full OpenAPI 3.0 specification at /openapi.yaml
  • Machine-readable documentation at /llms.txt
  • Postman collection at /bookingbrain-api.postman_collection.json

Documentation​

  • Developer portal launched at docs.bookingbrain.com
  • Quick start guide, authentication guide, error handling reference, booking flow walkthrough
  • AI integration guide with function calling examples
  • Interactive API reference with code samples in 6 languages