Availability and booking

These operations need the bookings.create capability. Dates are venue-local yyyy-MM-dd and times venue-local HH:mm.

1. Check availability

POST /public/v1/availability/search (check_availability) with the party size and a date, and optionally a time:

{ "venueId": "…", "date": "2026-10-16", "time": "20:00", "partySize": 4 }

The answer lists each free time with the booking types, lengths and deposits that fit it. When the asked time is taken, it offers alternatives in this order:

1. the nearest free times that day;
2. the same time on the next few days;
3. with "acrossVenues": true and a key covering several venues, the same time at the key’s other venues.

Offer the guest the alternatives; don’t book one they haven’t chosen.

2. Book

POST /public/v1/reservations (create_booking) with the time, party size, booking type and the guest’s name and phone number. Send an Idempotency-Key header so a retry never books twice.

The answer’s outcome tells you what happened:

Outcome	Status	What to tell the guest
booked	201	The booking is made; read out the summary with the reference.
unavailable	200	The time has just gone, or it’s outside what the venue takes online. Offer the alternatives in the answer.
needs_venue	200	The party is larger than the venue takes online. Offer to send an enquiry instead.

A booked answer’s state is confirmed, or held when the venue’s policy asks for a deposit. A held booking’s deposit says how much is due, that it is awaiting_payment, where the payment link went (sentTo) and when the link expires. The link goes to the guest automatically, and the booking confirms when they pay. If they don’t pay in time the hold is released.

The reference is eight digits, such as 4827 1936. The guest uses it with their phone number to find or change the booking.

Source channel

Every booking records where it came from. That comes from your key, not from the request: a voice agent’s key records voice-agent bookings, a chat agent’s key chat-agent bookings, and a partner’s key the partner. You can’t set it per request.

Event tickets

POST /public/v1/tickets holds tickets for an event date and returns a checkout link the guest opens to pay. Payment happens in the guest’s browser, so this operation has no MCP tool.