Listings API V1 (2.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Overview

The Listings API V1 is a venue-aggregated discovery interface.

The response root carries meta and listings[]. Each entry in listings[] is a ListingGroup — one per operator (venue-group / chain), carrying a groupName and an items[] array.

Each item represents a single venue (or a standalone event when no venue is known): it carries the venue name, a location, and a capabilities[] array. Each entry in capabilities[] is a Listing with exactly one capability (table_reservation or event_ticket), and carries its own media[]. A venue that also hosts a ticketed event therefore yields a single item with two capabilities — one for the venue, one for the event.

All bookable units (venue products, event ticket types, future capability types) are unified under a single bookableProducts[] array. Every entry is a single Bookable shape; capability-specific fields are nullable and the parent Listing's capability sets the context.

Temporal information (venue opening hours, event occurrences, blackout dates) is unified under a single availabilityOccurrence[] field of CalendarRules. Both capabilities use the same shape.

Pre-order assets (packages, menus) are unified under a single preorders container — applicable to either capability when the listing supports pre-orders.

ID formats — two distinct identifiers, named apart on purpose

listingId (Listing.id, as returned in /v1/listings and taken as the path parameter on GET /v1/listings/{listingId}) identifies a venue or a standalone event. It is 3 segments: {VenueGroupId}|{RmsSlug}|{ResourceId}. For a hybrid entity the event-side row uses the EventExt's own resource id (different RmsSlug + ResourceId) so the two rows are unambiguous.

compositeId (Bookable.compositeId — a specific bookable product/ticket type, used in bookableProducts[], and as the compositeId in /v1/availabilities and /v1/orders) is 4 segments: {VenueGroupId}|{RmsSlug}|{ResourceId}|{AdditionalId}.

These are two different identifiers for two different things, not two interchangeable formats for the same one — a listingId never appears where a compositeId is expected, or vice versa.

Download OpenAPI description

ListingsApiV1.json

ListingsApiV1.yaml

Overview

URL

https://www.bookabletech.com

Bookable

hello@bookabletech.com

Servers

Live

https://api.bookabletech.com

Sandbox

https://api-sandbox.bookabletech.com

Listings

Discover and retrieve bookable listings

Operations

Retrieve the full bookable catalogue (paginated, venue-aggregated)

Request

Returns the entire bookable catalogue available to the caller, paginated and venue-aggregated. Results are grouped by operator (ListingGroup); each group carries its venues (ListingItem), and each venue carries one Listing per capability it offers (table_reservation, event_ticket).

A venue that also hosts a ticketed event therefore appears once, with two entries in its capabilities[] — one per capability. Optional query filters (capability, name, location, features, date, …) narrow the catalogue; with no filters the whole catalogue is returned page by page.

Security

Live(Required scopes:

listing:read

) or Sandbox(Required scopes:

listing:read

)

Query

capabilitystring

Restrict results to a single capability. Venues are still returned aggregated; only their matching capability entries are included.

Enum"table_reservation""event_ticket"

Example: capability=table_reservation

listingNamestring[ 2 .. 100 ] characters

Filter by listing name — partial, case-insensitive match, with a semantic (vector similarity) fallback for near-matches. For an event listing, matches against either the event's own title or the name of the venue it's hosted at.

Example: listingName=dishoom

bookableProductNamestring[ 2 .. 100 ] characters

Filter to listings having at least one entry in bookableProducts[] whose name matches — partial, case-insensitive match, with a semantic (vector similarity) fallback for near-matches on the product/ticket type name (e.g. "Sunday Roast" also surfacing "Sunday Lunch").

Example: bookableProductName=sunday roast

operatorNamestring[ 2 .. 100 ] characters

Filter by operator (venue-group / chain) name.

Example: operatorName=stonegate

citystring[ 2 .. 100 ] characters

Example: city=london

areastring[ 2 .. 100 ] characters

Example: area=shoreditch

featuresArray of strings[ 1 .. 10 ] items

Filter by type / feature slugs (matched against types). Comma-separated list.

Example: features=dog_friendly,live_music

datestring(date)

Filter listings that have availability on a specific date (YYYY-MM-DD).

Example: date=2026-06-15

fieldsstring

Field selection using Google Fields syntax. Comma-separated list of top-level Listing fields to include. When omitted, all fields are returned.

Example: fields=id,name,capability,location(lat,lng,city),bookableProducts(compositeId,name)

pageNumberinteger>= 1

Default 1

pageSizeinteger[ 1 .. 100 ]

Default 20

sortBystring

Default "default"

Enum"default""name""city""area""relevance"

sortDirectionstring

Default "ASC"

Enum"ASC""DESC"

Headers

X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

X-Partner-Referencestring

Required for Bookable Agents — identifies the partner on whose behalf the request is made. Accepts either a partner reference (e.g. bottomlessbrunch.com) or a partner id (e.g. 288); a value matching a known partner reference resolves as that reference, otherwise it is treated as a partner id.

Example: bottomlessbrunch.com

curl -i -X GET \
  'https://api.bookabletech.com/v1/listings?capability=table_reservation&listingName=dishoom&bookableProductName=sunday+roast&operatorName=stonegate&city=london&area=shoreditch&features=dog_friendly%2Clive_music&date=2026-06-15&fields=id%2Cname%2Ccapability%2Clocation%28lat%2Clng%2Ccity%29%2CbookableProducts%28compositeId%2Cname%29&pageNumber=1&pageSize=20&sortBy=default&sortDirection=ASC' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com'

Responses

Paginated list of listings.

Headers

X-Correlation-IDstring

X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200

X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150

X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200

Body

metaobject

listingsArray of objects(ListingGroup)

Response

{
  "meta": {
    "currentPage": 1,
    "pageSize": 20,
    "totalItems": 1,
    "totalPages": 1
  },
  "listings": [
    { … }
  ]
}

Retrieve a single listing by its listingId

Request

Fetches one listing (a venue or a standalone event) by its listingId (Listing.id, {VenueGroupId}|{RmsSlug}|{ResourceId}, 3 segments — see the ID formats note above; not a Bookable.compositeId).

Returns the same shape as a single entry in GET /v1/listings' listings[] — groupName plus items[] — but items[] always holds exactly the one matching ListingItem, so a caller that already has a listingId (e.g. from a prior catalogue call) can re-fetch it directly without paginating the whole catalogue.

Security

Live(Required scopes:

listing:read

) or Sandbox(Required scopes:

listing:read

)

Path

listingIdstringrequired

A Listing.id — 3 segments, not a Bookable.compositeId.

Example: 29|CS|275cc44dd2e2496fba44857c9257443a

Headers

X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

X-Partner-Referencestring

Example: bottomlessbrunch.com

curl -i -X GET \
  'https://api.bookabletech.com/v1/listings/29|CS|275cc44dd2e2496fba44857c9257443a' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com'

Responses

The listing's operator group, with a single matching item in items[].

Headers

X-Correlation-IDstring

X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200

X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150

X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200

Body

groupNamestringrequired

Operator (venue-group / chain) display name.

Example: "Stonegate Group"

itemsArray of objects(ListingItem)required

Venues (and standalone events) belonging to this operator.

items[].namestringrequired

Venue name, or event name when there is no associated venue.

Example: "The Crown & Anchor"

items[].locationobject or null(Location)

Physical location. null for virtual listings (e.g. online events).

items[].capabilitiesArray of objects(Listing)required

The bookable capabilities offered at this venue.

items[].capabilities[].idstringrequired

listingId — {VenueGroupId}|{RmsSlug}|{ResourceId}. See the ID formats note above; not a Bookable.compositeId.

Example: "29|CS|275cc44dd2e2496fba44857c9257443a"

items[].capabilities[].namestringrequired

Example: "The Crown & Anchor"

items[].capabilities[].operatorNamestring or null

Operator (venue-group / chain) display name.

Example: "Stonegate Group"

items[].capabilities[].hostedBystring or null

Name of the venue hosting this listing. Populated for event_ticket listings whose event is associated with a physical venue (resolved from Collins); the venue's address is reflected in location. null when there is no associated venue (e.g. virtual events).

Example: "The Crown & Anchor"

items[].capabilities[].capabilitystring(Capability)required

Identifies a booking capability.

Enum"table_reservation""event_ticket"

Example: "table_reservation"

items[].capabilities[].typesArray of strings

Listing types and feature tag slugs, merged into a single list (e.g. venue categories like pub, bar plus feature tags like dog_friendly, live_music).

Example: ["pub","bar","dog_friendly","live_music"]

items[].capabilities[].contentstring or null

Example: "A traditional gastropub in the heart of Covent Garden, serving seasonal British food and an award-winning cask ale selection."

items[].capabilities[].faqsArray of objects or null(FaqItem)

Operator-managed public-facing FAQ list. Omitted/null when none are configured. For an event_ticket listing this is inherited from the hosting venue (hostedBy) when one exists — events have no FAQ list of their own.

Example: [{"question":"What is your cancellation policy?","answer":"See our **cancellation policy** [here](https://example.com/policy)."}]

items[].capabilities[].mediaArray of objects(MediaItem)

Photos and videos for this capability, cover first, with captions for alt text. An event_ticket listing without its own imagery shows its hosting venue's. Replaces the photos URL list removed in 2.0.0 — use the first type: photo item wherever you used photos[0]. Its URL can differ from the old one: once a venue has media in Bookable's library, these are Bookable-hosted files rather than the booking system's.

items[].capabilities[].phoneNumberstring or null

Example: "+442079461234"

items[].capabilities[].websitestring or null(uri)

Example: "https://www.crown-and-anchor.example/"

items[].capabilities[].availabilityOccurrenceArray of objects(CalendarRule)

Unified temporal description of the listing. Use recurring_with_time rules for weekly opening hours, specific_dates* for event dates or holiday closures, date_range* for seasonal availability, etc. Multiple rules may combine — status: closed overrides status: open. Rules sharing the same type, status and time window are aggregated: recurring rules combine their daysOfWeek, specific-date rules combine their dates.

items[].capabilities[].preordersobject or null(Preorders)

Pre-order assets for a listing. Either capability MAY expose packages and/or menus that can be selected at booking time. null when the listing does not support pre-orders.

items[].capabilities[].bookableProductsArray of objects(Bookable)required

All bookable units for this listing. Every entry is a Bookable — a single unified shape. Capability-specific fields are populated according to the row's capability.

items[].capabilities[].bookableProducts[].compositeIdstring

CompositeId of the bookable unit.

table_reservation → {VenueGroupId}|{RmsSlug}|{VenueId}|{ProductId}
event_ticket → {VenueGroupId}|{RmsSlug}|{EventId}|{TicketTypeId}

Example: "29|CS|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"

items[].capabilities[].bookableProducts[].namestring

Example: "Dining Room"

items[].capabilities[].bookableProducts[].timeIntervalinteger or null

Example: 30

items[].capabilities[].bookableProducts[].categorystring or null

Example: "Dinner"

items[].capabilities[].bookableProducts[].spacesArray of objects or null(Space)

Spaces/areas available within this bookable product.

items[].capabilities[].bookableProducts[].preordersobject or null(ProductPreorders)

Pre-order configuration for the bookable unit.

items[].capabilities[].bookableProducts[].depositobject or null(BookableDeposit)

Deposit configuration for the bookable unit.

items[].capabilities[].bookableProducts[].autoConfirmRuleobject(AutoConfirmRule)

items[].capabilities[].bookableProducts[].noAvailabilityActionstring or null

Example: "waitlist"

items[].capabilities[].bookableProducts[].priceobject or null(Price)

Monetary amount with currency.

items[].capabilities[].bookableProducts[].capacityobject or null(Capacity)

Capacity for a ticket type.

items[].capabilities[].bookableProducts[].visibilitystring or null

Example: "on_sale"

items[].capabilities[].bookableProducts[].availabilityOccurrenceOverridesArray of objects or null(CalendarRule)

Bookable-scoped CalendarRule entries that refine or restrict the listing-level availabilityOccurrence for this specific bookable unit (event sessions, exceptional dates, closures, …). Same shape as Listing.availabilityOccurrence; status: closed overrides status: open.

Response

{
  "groupName": "Stonegate Group",
  "items": [
    { … }
  ]
}

Check availability for multiple bookable products in one call

Request

Batch availability check. Modelled as a command (POST), not a search.

The request carries root-level date, quantity and optional time, plus a bookableProducts[] list. Each entry has a required compositeId and may override date, quantity and time. When an entry omits any of those, the root-level value is used.

quantity carries the count for either capability, same as in POST /v1/orders — number of covers for a table reservation, number of tickets for an event-ticket line.

Every entry must end up with date and quantity resolved (either from the entry or the root). time is optional — event capabilities are queried by date alone; for table reservations it narrows the slot when supplied. An entry that cannot resolve date and quantity is reported as an error result and does not block the others.

Searches run independently: a failure on one compositeId yields an error on that result only — all other results are returned normally. The response carries one AvailabilityResult per requested compositeId, preserving request order.

There is no 404 response: an unknown/nonexistent compositeId is not a request-level failure — it's reported as an error on that entry's AvailabilityResult, same as any other per-entry failure (e.g. unresolved date/quantity), never as an HTTP-level not-found for the whole call.

Security

Live(Required scopes:

listing:read

) or Sandbox(Required scopes:

listing:read

)

Headers

X-Correlation-IDstring

Optional ID for cross-system transaction tracking.

Example: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA

X-Partner-Referencestring

Example: bottomlessbrunch.com

Bodyapplication/jsonrequired

datestring or null(date)

Default booking date (YYYY-MM-DD), inherited by entries that omit it.

Example: "2026-06-15"

quantityinteger or null>= 1

Default quantity, inherited by entries that omit it — same field as OrderItem.quantity. For a table_reservation bookable, quantity is the number of people (covers); for an event_ticket bookable, quantity is the number of tickets.

Example: 4

timestring or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$

Optional default start time (HH:mm), inherited by entries that omit it.

Example: "19:00"

durationinteger or null

Optional default duration (minutes), inherited by entries that omit it.

Example: 90

bookableProductsArray of objects(AvailabilityProductRequest)[ 1 .. 100 ] itemsrequired

Bookable products to check. One result is returned per entry.

bookableProducts[].compositeIdstringrequired

CompositeId of the bookable product to check.

Example: "29|CS|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"

bookableProducts[].datestring or null(date)

Overrides the root date for this entry.

Example: "2026-06-15"

bookableProducts[].quantityinteger or null>= 1

Overrides the root quantity for this entry — number of people for a table_reservation bookable, number of tickets for an event_ticket bookable.

Example: 2

bookableProducts[].timestring or null^([0-1]?[0-9]|2[0-3]):[0-5][0-9]$

Overrides the root time for this entry.

Example: "20:00"

bookableProducts[].durationinteger or null

Overrides the root duration for this entry.

Example: 90

curl -i -X POST \
  https://api.bookabletech.com/v1/availabilities \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Correlation-ID: 11C46F5F-CDEF-4865-94B2-0EE0EDCC26DA' \
  -H 'X-Partner-Reference: bottomlessbrunch.com' \
  -d '{
    "date": "2026-06-15",
    "quantity": 4,
    "time": "19:00",
    "bookableProducts": [
      {
        "compositeId": "29|CS|275cc44dd2e2496fba44857c9257443a|prod1"
      },
      {
        "compositeId": "29|CS|275cc44dd2e2496fba44857c9257443a|prod2",
        "quantity": 2,
        "time": "20:00"
      },
      {
        "compositeId": "29|CS|999|prod3"
      }
    ]
  }'

Responses

One result per requested compositeId. Each result carries either availability (success) or error (failure); never both.

Headers

X-Correlation-IDstring

X-RateLimit-Limitinteger

Maximum number of requests allowed per window.

Example: 200

X-RateLimit-Remaininginteger

Number of requests remaining in the current window.

Example: 150

X-RateLimit-Resetinteger(int64)

Unix timestamp (seconds since epoch) when the current rate-limit window resets.

Example: 1741651200

Bodyapplication/json

resultsArray of objects(AvailabilityResult)required

One result per requested compositeId, in request order.

results[].compositeIdstringrequired

The compositeId this result refers to.

Example: "29|CS|275cc44dd2e2496fba44857c9257443a|e4d909c290d0fb1ca068ffaddf22cbd0"

results[].availabilityobject(Availability)

Availability for a single bookable product. Mirrors the BookingApi AvailabilityResponse.

results[].errorobject(ServerError)

Response

application/json

{
  "results": [
    { … },
    { … },
    { … }
  ]
}

Orders

Create and manage orders

Operations

Listings API V1 (2.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Overview

ID formats — two distinct identifiers, named apart on purpose

Listings

Retrieve the full bookable catalogue (paginated, venue-aggregated)

Request

Responses

Was this helpful?

Retrieve a single listing by its listingId

Request

Responses

Was this helpful?

Check availability for multiple bookable products in one call

Request

Responses

Was this helpful?

Orders

Listings API V1 (2.0.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from ClaudeConnect to CursorInstall MCP server on CursorConnect to VS CodeInstall MCP server on VS Code

Overview

ID formats — two distinct identifiers, named apart on purpose

Listings

Retrieve the full bookable catalogue (paginated, venue-aggregated)

Request

Responses

Was this helpful?

Retrieve a single listing by its listingId

Request

Responses

Was this helpful?

Check availability for multiple bookable products in one call

RequestExpand all

Responses

Was this helpful?

Orders

Listings API V1 (2.0.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude
Connect to Cursor
Install MCP server on Cursor
Connect to VS Code
Install MCP server on VS Code

Request