Skip to main content

Operations API

The BookingFlow Operations API is a REST interface for running a caravan park — the equivalent of the Stripe API, but for park operations. Search availability, create bookings, manage rates and inventory, record electricity meter readings, generate Xero invoices, and receive signed webhooks. It is designed to be driven by humans and agents: any AI assistant holding an API key can operate a park end-to-end.

curl https://europe-west1-bookingflow-6fd8c.cloudfunctions.net/api/v1/bookings \
  -H "Authorization: Bearer bf_live_..."

Where to start​

PageContents
QuickstartFirst requests, curl, and the agent workflow (paste meter readings → generate invoices)
ConventionsAuthentication, errors, idempotency, pagination, expansion, metadata, webhooks
Resource referenceAccommodations · Caravans · Availability · Bookings · Customers · Events · Invoices · Meter readings · Pitches · Rates · Webhook endpoints

The machine-readable contract is the [OpenAPI 3.1 specification] (https://github.com/bookingflow/bookingflow/blob/main/functions/openapi.yaml) in functions/openapi.yaml, which a route-drift test keeps in sync with the implemented Express routes.

Design principles​

The API follows the conventions that make the Stripe API a pleasure to integrate with:

  • Predictable resources — every object has id, object, created; relations are ids; money is minor units; timestamps are Unix seconds.
  • Safe by default — booking creation re-checks inventory and prices the stay server-side inside a transaction; the API cannot oversell or undercharge.
  • Retries never hurt — every POST honours an Idempotency-Key, and invoice generation is naturally idempotent per closing meter reading.
  • Errors you can act on — one error envelope with a machine-readable code, the offending param, and a doc_url.
  • Agent-first — bulk endpoints report per-row results; partial success is explicit; every failure carries a human-readable reason.

Environments​

EnvironmentBase URL
Productionhttps://europe-west1-bookingflow-6fd8c.cloudfunctions.net/api
Testhttps://europe-west1-bookingflowtest.cloudfunctions.net/api

The architecture decision record is [ADR-008: Operations API] (https://github.com/bookingflow/bookingflow/blob/main/docs/docs/adr/008-operations-api.md).