Booking Engine API

Same as /health/ready (aggregate check). No auth. Returns 200 (all healthy) or 503. Response: {"status": "ok"|"unavailable", "checks": {"database": bool, "redis": bool, ...}}

Liveness only — no dependency checks. No auth. Response: {"status": "ok"}. Always 200 if the process is up.

Readiness — checks Postgres + Redis connectivity. No auth. Response: {"status": "ok"|"unavailable", "checks": {...}}. 200 or 503.

No auth. Creates a user account and returns a bearer token. Body:

Response 201: UserResource (id, name, email, is_platform_admin, created_at) + meta.token (plaintext bearer token, shown once — store it). Errors: 422 VALIDATION_FAILED (email taken, password too short/mismatched, etc.)

No auth. Exchanges credentials for a new bearer token (does not revoke existing tokens). Body:

Response 200: UserResource + meta.token. Errors: 422 VALIDATION_FAILED with details.email = ["These credentials do not match our records."] on bad credentials (deliberately the same message whether the email doesn't exist or the password is wrong).

Auth: Sanctum. Revokes the token used for this request only (other sessions stay valid). Response: 204 No Content.

Auth: Sanctum. Returns the current user. Response 200: UserResource.

Auth: Sanctum. Lists organizations the current user belongs to (platform admins see all). Response 200: array of OrganizationResource under data. OrganizationResource fields: id, name, slug, timezone, currency, status (active|suspended), settings (object, see below), my_role (present when loaded via membership — organization_owner|organization_manager|staff), created_at, updated_at.

settings keys and defaults: booking_min_notice_minutes (60), booking_max_days_ahead (90), cancellation_notice_minutes (1440), default_booking_duration (60), payment_timeout_minutes (30), late_cancellation_refund_percent (50), reminder_offsets_minutes ([1440,120,15]), resource_allocation_strategy ("first_available").

Auth: Sanctum. Creates an organization; the creator becomes its Owner. Body:

Response 201: OrganizationResource. Errors: 422 on invalid/duplicate slug, invalid timezone.

Auth: Sanctum, any member of the org. Response 200: OrganizationResource. Errors: 403 if not a member.

Auth: Sanctum + organizations.update permission (Owner/Manager). Body: any subset of name, slug (same rules, unique excluding self), timezone, currency, status (active|suspended), settings (merged, not replaced-wholesale by the request handler — sent object is passed straight to update()). Response 200: OrganizationResource. Errors: 403 without permission, 422 invalid fields.

Auth: Sanctum + analytics.read permission — Owner-only (Manager/Staff get 403, unlike most other read endpoints they share with Owner). Query params: date_from (date, optional, default 30 days ago), date_to (date, optional, default today; must be ≥ date_from). Response 200 (data):

{
  "period": {"from": "<iso8601>", "to": "<iso8601>"},
  "bookings": {"total": int, "by_status": {"<status>": int, ...}},
  "cancellation_rate": float,               // percent, 0-100
  "revenue": [{"currency": "USD", "amount": float}, ...],  // "booked" revenue: sum of price for confirmed/checked_in/completed bookings, NOT net of refunds
  "top_services": [{"id": "srv_...", "name": "...", "bookings": int}, ...],   // top 5
  "top_resources": [{"id": "res_...", "name": "...", "bookings": int}, ...]   // top 5
}

Errors: 403 PERMISSION_DENIED if not Owner.

Auth: Sanctum + locations viewAny (any member can read). Query: organization_id (required). Response 200: array of LocationResource (id, organization_id, name, timezone, type, address, latitude, longitude, status, created_at, updated_at). Errors: 422 if organization_id missing.

Auth: Sanctum + create permission. Body: organization_id (required, exists), name (required, max 255), timezone (required, valid tz), type (optional, physical|online, default physical), address (nullable, max 255), latitude/longitude (nullable, numeric, in valid geo ranges). Response 201: LocationResource.

Auth: Sanctum + view. Response 200: LocationResource.

Auth: Sanctum + locations.update permission. Body: any subset of name, timezone, type, address, latitude, longitude, status. Response 200: LocationResource.

Auth: Sanctum + delete permission. Response: 204.

Auth: Sanctum. Query: organization_id (required). Response 200: array of ResourceGroupResource (id, organization_id, name, created_at, updated_at).

Auth: Sanctum + create permission. Body: organization_id (required), name (required, max 255). Response 201: ResourceGroupResource.

Auth: Sanctum + view. Response 200: ResourceGroupResource.

Auth: Sanctum + update permission. Body: name (required, max 255). Response 200: ResourceGroupResource.

Auth: Sanctum + delete permission. Response: 204.

Auth: Sanctum, or API key with resources:read scope. Query: organization_id (required). Response 200: array of ResourceResource (id, organization_id, location_id, resource_group_id (nullable), name, description, type, capacity (int, default 1), status, metadata (object), created_at, updated_at).

Auth: Sanctum + create permission. Body: organization_id (required), location_id (required, exists, must belong to same org), resource_group_id (nullable, exists, must belong to same org), name (required, max 255), description (nullable), type (required, free-text, e.g. room/person/equipment), capacity (optional int ≥1, default 1), metadata (optional object). Response 201: ResourceResource. Errors: 422 if location/group belongs to a different organization.

Auth: Sanctum, or API key with resources:read scope. Response 200: ResourceResource.

Auth: Sanctum + update permission. Body: any subset of location_id, resource_group_id (nullable to unset), name, description, type, capacity, status, metadata. Response 200: ResourceResource.

Auth: Sanctum + delete permission. Response: 204.

Auth: Sanctum. Query: organization_id (required). Response 200: array of ServiceResource: id, organization_id, name, description, duration_minutes, buffer_before_minutes, buffer_after_minutes, price (float), currency, pricing_rules (object|null — see below), cancellation_policy (object|null — see below), status, payment_mode (none|full|deposit|pay_after), deposit_amount (float|null), resource_ids (array, present only when resources are eager-loaded — always true from these endpoints), created_at, updated_at.

Auth: Sanctum + create permission. Body:

Pricing rules shape — all keys optional, price computed once at booking creation and never changes after:

{
  "weekend_price": 55.00,                                    // overrides base price on Sat/Sun (resource's local timezone)
  "time_of_day_multipliers": [{"start":"18:00","end":"22:00","multiplier":1.20}],  // compounds if multiple windows match the booking's local start time
  "occupancy_surcharge": {"threshold_percent": 80, "multiplier": 1.15}  // applies if the resource's booked capacity for that slot exceeds threshold_percent (only meaningful for capacity > 1 resources)
}

Cancellation policy shape — both keys optional, independently override the organization's cancellation_notice_minutes/late_cancellation_refund_percent:

{"notice_minutes": 2880, "refund_percent": 25}

Response 201: ServiceResource. Errors: 422 (deposit > price, resource from another org, malformed pricing_rules/cancellation_policy entries).

Auth: Sanctum + view. Response 200: ServiceResource.

Auth: Sanctum + update permission. Body: any subset of the store fields above (all sometimes); sending resource_ids re-syncs the linked resources (omit to leave unchanged). Response 200: ServiceResource.

Auth: Sanctum + delete permission. Response: 204.

Auth: Sanctum + view resource. Response 200: array of ScheduleRuleResource: id, day_of_week (0=Sunday..6=Saturday), start_time/end_time ("HH:MM"), valid_from/valid_until (date|null).

Auth: Sanctum + update resource. Replaces the entire weekly schedule (delete-then-recreate in one transaction). Body: {"rules": [...]} — rules required (may be empty array to clear the schedule entirely), each item: day_of_week (required, int 0-6), start_time/end_time (required, HH:MM, end must be after start), valid_from/valid_until (nullable date, valid_from ≤ valid_until if both given). Response 200: array of ScheduleRuleResource (the new schedule).

Auth: Sanctum + view resource. Response 200: array of ScheduleExceptionResource: id, date, type (closed|custom_hours), start_time/end_time (only set for custom_hours).

Auth: Sanctum + update resource. Body: date (required, must not already have an exception for this resource), type (required, closed|custom_hours), start_time/end_time (required if type=custom_hours, HH:MM, end after start). Response 201: ScheduleExceptionResource.

Auth: Sanctum + update resource. Response: 204. 404 if the exception doesn't belong to that resource.

Auth: Sanctum + view resource. Query: resource_id (required). Response 200: array of ResourceBlockResource: id, resource_id, starts_at, ends_at, reason (maintenance|private_event|manual_block|external_calendar|other), notes, created_at.

Auth: Sanctum + update resource. Body: resource_id (required), starts_at (required, date), ends_at (required, date, after starts_at), reason (required, enum above), notes (nullable). Response 201: ResourceBlockResource.

Auth: Sanctum + update the block's resource. Response: 204.

Auth: Sanctum + integrations.manage (Owner-only). Response 200: {"data": {"authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?..."}} — redirect the browser here.

No auth (Google's redirect lands here; a signed one-time state param — 10 min TTL, cached server-side — proves legitimacy, not a bearer token). Query: code (from Google), state (required, from the authorize step). Response 200 or 201 (201 the very first time a connection is created for that resource, 200 on reconnect): CalendarConnectionResource: id, resource_id, provider ("google"), external_calendar_id, status (active|disabled|error), busy_periods_synced_at, created_at. Errors: 422 VALIDATION_FAILED if state is invalid/expired/already used, or Google reported error (user denied access).

Auth: Sanctum + integrations.manage. Response 200: CalendarConnectionResource. 404 if no connection exists for this resource.

Auth: Sanctum + integrations.manage. Response: 204. 404 if none exists.

Auth: Sanctum, or API key with availability:read scope. Computes bookable slots honoring schedule, exceptions, resource blocks, existing bookings/holds, capacity, synced calendar busy periods, min-notice and max-horizon organization settings. Query params:

Response 200: {"data": [{"date": "2026-08-20", "slots": [{"start": "<iso8601>", "end": "<iso8601>", "resource_id": "res_..."}]}]} — one entry per date that has ≥1 free slot, sorted by date then start time.

Identical to the above — same controller, same params/response — but no authentication required (rate-limited at 20/min/IP via the public limiter instead of the authenticated api limiter).

Auth: Sanctum. Body: resource_id (required), service_id (required, must be offered on that resource), start_at (required, date ≥ now), party_size (optional, int ≥1, default 1, must not exceed the resource's capacity — 422 if it does). Response 201: BookingHoldResource: id, resource_id, service_id, start_at, end_at, expires_at, party_size. Errors: 409 BOOKING_SLOT_UNAVAILABLE if the resource's capacity for that slot (summed across other active bookings + holds) can't fit this party_size; 422 if party_size exceeds the resource's total capacity, or the resource is closed/outside working hours at that time.

Auth: Sanctum, only the hold's own creator. Response: 204. 403 if it's someone else's hold.

Auth: Sanctum, or API key bookings:read scope. Lists the caller's own bookings plus any organization they can read bookings for (platform admins see everything). Query filters (all optional): status, resource_id, service_id, customer_id, location_id, date_from, date_to (all compare against start_at), sort (start_at|created_at, prefix with - for descending; default -start_at). Response 200: cursor-paginated (20/page) array of BookingResource: id, organization_id, customer_id, service_id, resource_id, location_id, start_at, end_at, status (pending|held|awaiting_payment|confirmed|checked_in|completed|cancelled|no_show|expired), price (float, fixed at creation), currency, notes, party_size, cancelled_at, created_at, updated_at.

Auth: Sanctum, or API key bookings:write scope. Body:

Response 201: BookingResource. Errors: 409 BOOKING_SLOT_UNAVAILABLE (with details.alternatives — up to 3 nearby free same-day slots — for genuine capacity/overlap conflicts) if the slot isn't free, or auto-allocation found no eligible resource at all; 422 for validation issues (party_size too big, hold/resource/service mismatch, hold expired); 403 if customer_id given without permission.

Auth: Sanctum, or API key bookings:read scope, view policy (own booking or org read permission). Response 200: BookingResource.

Auth: Sanctum only, bookings.update permission (staff action). Transitions pending → confirmed. Response 200: BookingResource. Errors: 422 if the transition isn't valid from the booking's current status.

Auth: Sanctum only, bookings.update permission. Transitions confirmed → checked_in. Response 200: BookingResource.

Auth: Sanctum only, bookings.update permission. Transitions checked_in → completed. Response 200: BookingResource.

Auth: Sanctum, or API key bookings:write scope; own booking or bookings.cancel permission. Evaluates the cancellation policy and auto-refunds any paid payment accordingly. Response 200: BookingResource + meta.free_cancellation (bool — whether this cancellation fell inside the free window). Errors: 409 BOOKING_ALREADY_CANCELLED if already cancelled.

Auth: Sanctum, or API key bookings:write scope; own booking or bookings.update permission. Atomically moves the booking to a new time — price is not recalculated even if the new slot would price differently (price is fixed once, at creation). Body: start_at (required, date ≥ now). Response 200: BookingResource. Errors: 409 BOOKING_SLOT_UNAVAILABLE (with alternatives) if the new slot isn't free; 422 BOOKING_CANNOT_BE_RESCHEDULED if the booking's status doesn't allow it (only pending/held/awaiting_payment/confirmed can be rescheduled).

Auth: Sanctum, or API key bookings:write scope. Starts a Stripe PaymentIntent for a booking whose service requires payment — Idempotent via the idempotent middleware. Response 201: PaymentResource (id, booking_id, provider, amount, amount_refunded, currency, status, failure_reason, paid_at, created_at, updated_at) + client_secret (Stripe client secret to complete payment client-side). Errors: 422 if the booking doesn't currently need payment, or already has an active PaymentIntent.

Auth: Sanctum, or API key bookings:write scope (same group as /bookings). Creates a weekly-recurring series, e.g. "every Tuesday 18:00, 8 weeks" — each occurrence goes through the exact same path as a single POST /bookings (capacity, pricing, calendar sync, webhooks all fire normally). Requires an explicit resource_id — auto-allocation is deliberately not available here (it could pick a different resource per occurrence, defeating the point of a recurring series). Body:

all_or_nothing: every occurrence must be free, or none are created (checked/created inside one outer transaction — a conflict on any occurrence rolls back everything already committed). Response is a 409 (the specific conflicting occurrence's own error, with alternatives) if it fails. book_available: creates whichever occurrences are free, skips the rest — always returns 201 even if some/all were skipped.

Response 201 (data):

{
  "recurring_booking_id": "<ulid>",     // groups the created bookings; also stored as `recurring_booking_id` on each Booking row
  "strategy": "all_or_nothing"|"book_available",
  "bookings": [ <BookingResource>, ... ],           // the ones actually created
  "skipped": [{"start_at": "<iso8601>", "reason": "<message>"}, ...]   // book_available only; always [] for all_or_nothing
}

Errors: 409 BOOKING_SLOT_UNAVAILABLE (all_or_nothing failure — nothing created); 422 validation; 403 if customer_id given without permission.

No auth. Rate-limited at 20/min/IP (public limiter). Body: same as POST /bookings (resource_id optional → auto-allocation, location_id, service_id required, start_at required, party_size optional, notes optional), minus hold_id/customer_id, plus:

Response 201: BookingResource — the booking's customer_id is the (possibly newly-created) guest user. Errors: 409 BOOKING_SLOT_UNAVAILABLE; 422 validation; 429 RATE_LIMIT_EXCEEDED (much more likely here than on authenticated endpoints).

Auth: Sanctum. Lists payments for the caller's own bookings plus any organization they have payments.read for. Query filters (optional): booking_id, status. Response 200: cursor-paginated (20/page) array of PaymentResource.

Auth: Sanctum + view policy. Response 200: PaymentResource.

Auth: Sanctum + refund policy (payments.manage permission). Full or partial refund. Body: amount (optional, numeric, >0 — omit for a full refund of whatever's left unpaid-back). Response 200: PaymentResource (updated amount_refunded/status). Errors: 422 if the payment can't be refunded (not paid) or the amount exceeds what's refundable.

Auth: Sanctum. Lists the caller's own entries plus any organization they can read bookings for. Response 200: cursor-paginated (20/page) array of WaitlistEntryResource: id, customer_id, service_id, resource_id (nullable — null means "any resource offering the service"), desired_start_at, status (waiting|notified|cancelled), created_at, updated_at.

Auth: Sanctum. Join the waitlist for a slot that's currently taken — automatically notified if it frees up. Body: service_id (required), resource_id (optional — omit to be notified for any resource offering the service), desired_start_at (required, date, after now). Response 201: WaitlistEntryResource.

Auth: Sanctum, own entry only. Response: 204.

Auth: Sanctum + integrations.manage (Owner-only). Query: organization_id (required). Response 200: array of ApiKeyResource: id, organization_id, name, key_prefix (first chars of the key, for identification — never the full key), scopes (array of bookings:read|bookings:write|availability:read|resources:read), expires_at (nullable), revoked_at (nullable), last_used_at (nullable), created_at. Never includes the plaintext key.

Auth: Sanctum + integrations.manage. Body: organization_id (required), name (required, max 255), scopes (required, array, ≥1, each one of the 4 values above), expires_at (optional, nullable date, must be in the future). Response 201: ApiKeyResource + key (the plaintext key, format booking_live_... — shown exactly once, never retrievable again).

Auth: Sanctum + integrations.manage. Revokes (soft — sets revoked_at, row kept for audit history, not hard-deleted). Response: 204.

Auth: Sanctum + integrations.manage. Query: organization_id (required). Response 200: array of WebhookEndpointResource: id, organization_id, url, events (array of booking.created|booking.confirmed|booking.cancelled|payment.completed), status (active|disabled), created_at, updated_at. Never includes the signing secret.

Auth: Sanctum + integrations.manage. Body: organization_id (required), url (required, valid URL, must start with https://), events (required, array ≥1, values from the enum above). Response 201: WebhookEndpointResource + secret (40-char signing secret, shown once — use it to verify X-Webhook-Signature, see below).

Auth: Sanctum + integrations.manage. Body: any subset of url, events, status. Response 200: WebhookEndpointResource.

Auth: Sanctum + integrations.manage. Response: 204.

Delivery signing: every delivery POSTs the exact event payload JSON with headers X-Webhook-Signature (hash_hmac('sha256', "{timestamp}.{body}", secret)), X-Webhook-Timestamp, X-Webhook-Event (e.g. booking.confirmed), X-Webhook-Id. Retries on non-2xx with backoff 1m, 5m, 30m, 2h, 12h (5 attempts) before marking failed.

Auth: Sanctum + integrations.manage on the relevant org (platform admins see all). Query filters (optional): webhook_endpoint_id, status (pending|delivered|failed). Response 200: cursor-paginated (20/page) array of WebhookDeliveryResource: id, webhook_endpoint_id, event_type, attempt (int), status_code (nullable int), response_body (nullable, truncated to 2000 chars), duration_ms (nullable), status (pending|delivered|failed), next_retry_at (nullable), created_at.

Auth: Sanctum + retry policy (integrations.manage). Manually retries a failed delivery — gives it a fresh 5-attempt budget. Response 200: WebhookDeliveryResource (status reflects the outcome — synchronous under the sync queue driver locally, async in production). Errors: 422 VALIDATION_FAILED if the delivery isn't currently failed (e.g. still pending or already delivered).

No Sanctum auth — verified via the Stripe-Signature header instead. Configure this URL in the Stripe Dashboard (or stripe listen --forward-to). Body: raw Stripe event payload (as sent by Stripe). Response 200: {"status": "accepted"} (queued for processing) or {"status": "already_received"} (duplicate event_id, safe no-op — Stripe retries aggressively on anything but 2xx). Response 400: {"error": {"code": "INVALID_SIGNATURE"}} if the signature doesn't verify.