Your site, our data, in three lines

List published events

Returns a page slice plus a total that reflects the filtered set, which is what makes a pager correct. Only events published to web are ever returned. Read ticketSales before you render a Book button: an event whose tickets are sold on Ticketmaster reports bookable false and carries externalTicketUrl instead.

Keyspk_sk_Scopeevents

Parameters

window'upcoming' | 'recent' | 'archived' | 'past'

upcoming is future events ascending. recent is the N most-recent past events. archived is past events beyond that recent window. past is every past event, flat. Default upcoming

firstinteger >= 0

Zero-based offset of the first row to return. Default 0

rowsinteger 1-50

Page size. Capped at 50 server-side. Default 20

recentCountinteger 1-50

Where the recent window ends and archived begins. Send the same value to both or the two windows drift and an event appears twice or not at all. Default 9

searchstring 1-120

Case-insensitive match on the event name.

typestring 1-120

Exact published event-type name, as returned by /events/types.

sort'date_asc' | 'date_desc' | 'name_asc' | 'name_desc'

Omit it and each window keeps its natural order, so the parameter is backward-compatible.

Returns{ data: PublicEvent[], total: number }

List event types that have events

Only types that actually have published events in the requested window. Use this to build a filter that never offers an option returning zero results - never derive the list from one page of events.

Keyspk_sk_Scopeevents

Parameters

window'upcoming' | 'past'

Which side of today to look at. Default upcoming

Returns{ data: { name: string, color: string | null }[] }

Read one event in full

The only place seatingMode, ticket tiers, bundles and live remaining counts are returned. Always read this before starting a booking - list rows do not carry seating. acceptsPromoCodes is true when the event has a live promo code, so show a code box only then.

Keyspk_sk_Scopeevents

Parameters

idstring (path)required

The event id.

ReturnsPublicEventDetail

Availability snapshot

The current status of every bookable seat or table. Use it to paint the map first, then keep it current from the stream. It is also the resync path after a dropped connection.

Keyspk_sk_Scopeevents

Parameters

idstring (path)required

The event id.

Returns{ objects: { id, capacity, taken, available, status: 'available' | 'held' | 'sold', price }[] }

Live availability over SSE

A server-sent event stream that pushes availability as it changes, so a seat someone else takes greys out on your page without a poller. It sends a snapshot event on connect and a seats event, with the same shape as GET /events/:id/seats, every time availability changes. The key goes in the query because EventSource cannot send headers; the bar streams take theirs the same way.

Keyspk_sk_Scopeevents

Parameters

idstring (path)required

The event id.

keystring (query)

Your publishable key, when you cannot set a header. Never put a secret key in a query string.

Returnsevent: snapshot | seats data: { objects: [...] }

Create a booking and start checkout

Holds the selection for 15 minutes and returns a Stripe Checkout redirect URL. Send at least one of items, bundles or seats; the API prices them from the event, so the body carries no amounts. From a publishable key the request is a browser form, so it carries a Turnstile captchaToken where the API has Turnstile enabled and a hidden hp honeypot that must stay empty; a secret key from your server needs neither. One address may hold at most three open bookings per event at a time.

Keyspk_sk_Scopeevents

Body

eventIdstringrequired

The event being booked.

captchaTokenstring

Required from a publishable key when the API has Turnstile enabled: the token the Turnstile widget hands you. The seat-map embed sends it for you when it has a site key.

hpany

A honeypot. Render it hidden and send it empty; a filled value is answered with a success-shaped body and nothing is booked.

buyer.firstNamestring 1-100required

Buyer first name.

buyer.lastNamestring 1-100required

Buyer surname.

buyer.phonestring 1-50required

Required - this is how the venue reaches the buyer on the night.

buyer.emailstring email

Optional, but the ticket cannot be emailed without it.

buyer.marketingOptInboolean

Records marketing consent with its source and evidence. Leave it out rather than defaulting it true.

items[]{ ticketTypeId, quantity 1-100 }

General-admission tickets. Up to 50 entries.

bundles[]{ bundleId, quantity 1-100 }

Ticket bundles, where the event offers them.

seats[]{ id, quantity, ticketTypeId? }

Reserved seating. 1 to 50 entries, each a seat or table id from /seats.

promoCodestring

A promo code the buyer entered, in any case. It is checked again when the booking is made, so a code that ran out after your quote is refused with its own error rather than silently ignored.

successUrlurl

Where the buyer returns after paying. This and the two below must be https, on the VenueSpine app, the storefront, or an origin listed under the key’s Return origins (up to ten per key); anything else is refused with RETURN_URL_NOT_ALLOWED.

cancelUrlurl

Where the buyer returns if they cancel at the payment page.

failureUrlurl

Where the buyer returns if payment fails.

Returns{ bookingId, reference, status: 'pending_payment' | 'paid', redirectUrl }

Price a selection, with or without a promo code

Prices exactly what POST /bookings would charge, so you can show a promo code’s discount before the buyer pays. It holds nothing and books nothing: the booking checks the code again. subtotal is the amount the booking will charge, the same figure GET /bookings/:id returns; gross is before the code. A code counts in tickets and never discounts a bundle. Attempts that carry a code are rate limited per address.

Keyspk_sk_Scopeevents

Body

eventIdstringrequired

The event being booked.

items[] / bundles[] / seats[]as for POST /bookingsrequired

The same selection you will book. Send at least one.

promoCodestring

The code to apply. Leave it out for plain pricing.

Returns{ currency, gross, discount, subtotal, promoCode: { code, discountType, discountValue, tickets } | null, lines: [{ name, detail, quantity, unitPrice, lineTotal, discount }] }

Poll a booking

Read the booking after the buyer returns from checkout. Poll this rather than trusting the redirect - the redirect tells you the buyer came back, not that the money arrived. subtotal is the amount in pounds; the tickets themselves come from GET /bookings/:id/tickets with a secret key.

Keyspk_sk_Scopeevents

Parameters

idstring (path)required

The booking id.

Returns{ id, reference, status: 'pending_payment' | 'paid' | 'failed' | 'expired' | 'cancelled' | 'refunded', subtotal, discount, promoCode, currency }

Read the tickets on a paid booking

The issued tickets with the code the door scanner reads, the seat label where the event is reserved seating, and whether each has been scanned in. Secret key only: a code is the ticket, so this never goes to a browser. Tickets are issued on demand the first time a paid booking is read. A booking that is not paid answers with an empty list.

Keyssk_Scopeevents

Parameters

idstring (path)required

The booking id.

Returns{ tickets: [{ id, code, label, ticketTypeName, seatLabel, sequence, status, checkedInAt }] }

List catalogue categories

The published category tree for a catalogue-led account.

Keyspk_sk_Scopecatalog

Returns{ data: Category[] }

List products and packages

Published products with pricing, filterable by category. Each product carries its allergens and diets as keys, and its modifierGroups: the choices a guest makes when ordering it (a side, a doneness, extras), each group with minChoices, maxChoices and modifiers that each carry a priceDelta added to the product price. A group with minChoices of 1 or more is a required choice. Show the groups on your menu page; ordering with them from the seat is not yet open on the public bar order endpoint.

Keyspk_sk_Scopecatalog

Parameters

categorystring

Restrict to one category.

firstinteger

Offset. Default 0

rowsinteger

Page size. Default 20

Returns{ data: Product[], total: number }

Read one product

Full product detail including variants, package contents and modifierGroups (see the list endpoint for the shape).

Keyspk_sk_Scopecatalog

Parameters

idstring (path)required

The product id.

ReturnsProduct

List bar menu categories

The categories that hold something the till sells right now: an active special, or an active item that is not an ingredient. Any other category is left out, so your page never renders an empty section.

Keyspk_sk_Scopebar

ReturnsCategory[]

List bar menu items

Active stock items and specials with their prices, and only what the till sells: an ingredient (an item with "Sell it on the till" unticked, such as flour or mince) is left out, and total does not count it. Items are sold on the till unless marked, and specials always are. Cost prices and stock levels are never exposed. Where a category is poured by the tot or the glass, the per-serving price comes through resolved, whether it is set on the item or inherited from its category.

Keyspk_sk_Scopebar

Parameters

kind'stock' | 'special'

Restrict to ordinary items or to specials. Both are returned by default.

categoryIdstring

Restrict to one category.

searchstring

Match on name or SKU.

sort'name_asc' | 'name_desc' | 'price_asc' | 'price_desc'

Ordering. Default name_asc

firstinteger

Offset. Default 0

rowsinteger

Page size, up to 50. Default 20

Returns{ data: MenuItem[], total: number }

List published designed menus

The menus the account has designed in VenueSpine and published to a public page, each with the hosted page address. Render the page in a frame or a web view, or fetch its JSON with no key at /api/public/menus/{accountSlug}/{slug} - the document, the live price snapshot behind it and a QR code for the page - to draw it natively. Up to fifty, by name.

Keyspk_sk_Scopebar

Returns{ menus: [{ id, name, description, accountSlug, slug, publicUrl, publishedAt }] }

Is the bar taking guest orders for an event?

Whether guests at the event may order from the bar through your app or site right now. The venue sets a mode per event - off, during the show, whenever a till is open, or only once the bar opens it from the till - and ordering is open only inside that window and while a POS session is trading on the event. reason says which of those is missing: off, outside_window, no_open_session or not_opened (the bar has not opened it yet). Read it when your ordering screen opens, then follow GET /bar/ordering/stream rather than polling; it is never cached.

Keyspk_sk_Scopebar

Parameters

eventIdstringrequired

The event id or slug. Must be published to web on the account behind your key.

Returns{ enabled: boolean, window: 'off' | 'show' | 'always' | 'manual', opensAt, closesAt, tableService: boolean, note, reason: 'off' | 'outside_window' | 'no_open_session' | 'not_opened' | null }

Follow whether the bar is taking orders, live

A text/event-stream that sends the same shape as GET /bar/ordering as a status event on connect and again every time it changes - the venue flips the mode, a till opens, closes, locks or unlocks, or the bar opens ordering from the till. Keep it open while your ordering screen is on screen and close it when the guest leaves, instead of polling. The key goes in the query because EventSource cannot set headers; publishable is fine.

Keyspk_sk_Scopebar

Parameters

eventIdstringrequired

The event id or slug.

keystring (query)required

Your publishable key. Never a secret key in a URL.

Returnsevent: status data: { enabled, window, opensAt, closesAt, tableService, note, reason }

Place a bar order for a paid guest

Send what a guest wants to the bar that is trading on the event. The guest is identified by a paid booking on the same event, so the till knows who ordered and, where the event is reserved seating, which table they sit at. Nothing is charged: the bar accepts the order into a tab and takes payment as it always does. Items are priced from the current menu at the moment the bar accepts. Requires an Idempotency-Key header; send the same key when you retry and you get the same order back with Idempotent-Replay: true. Secret key only.

Keyssk_Scopebar

Body

eventIdstringrequired

The event the guest is at.

bookingIdstringrequired

A paid booking on that event, made through your key. The order carries its buyer and seat.

service'table' | 'collect'

Bring it to the table, or the guest collects at the bar. table is refused when the venue has switched table service off for the event. Default table

tableLabelstring

Where the guest says they are, up to 60 characters. Ignored when the booking already has a seat; the seating plan wins.

items{ itemId, quantity, saleUnit?, note? }[]required

One to thirty lines from GET /bar/menu, up to twenty of each. saleUnit is unit or serving (serving only where the item is poured by the tot or glass; otherwise SERVING_NOT_SOLD). note is up to 255 characters and the bar sees it on the line.

notesstring

A note for the whole order, up to 500 characters.

customerIdstring

A VenueSpine customer id to attach when the booking itself has none. Ignored otherwise.

Returns{ id, reference, status, service, tableLabel, total, items: [{ name, quantity, unitPrice, lineTotal }], declinedReason, createdAt, cancellableUntil, updatedAt, statusToken }

Read an order back

The order as the bar sees it now. Needs the statusToken that came back when the order was placed; without it, or with the wrong one, the order does not exist as far as the caller is concerned. total is the accepted total once the bar has accepted, so it can differ from what was quoted if the menu changed in between.

Keyspk_sk_Scopebar

Parameters

idstring (path)required

The order id.

tokenstringrequired

The statusToken from the create response.

Returns{ id, reference, status: 'received' | 'accepted' | 'preparing' | 'ready' | 'delivered' | 'declined' | 'cancelled', service, tableLabel, total, items[], declinedReason, createdAt, cancellableUntil, updatedAt }

Let the guest cancel their order

Cancels an order the guest changed their mind about. Allowed for two minutes after it was placed - the read shape carries the deadline as cancellableUntil, so show a countdown and hide the button when it passes - and never once the bar has delivered it or taken payment for it. If the bar had already accepted the order into a tab, the unpaid tab is discarded and the till is told. Cancelling twice is harmless. Needs the statusToken. Secret key only.

Keyssk_Scopebar

Parameters

idstring (path)required

The order id.

Body

tokenstringrequired

The statusToken from the create response.

ReturnsThe order, as GET /bar/orders/:id, with status: cancelled

Follow an order over server-sent events

A text/event-stream that sends a status event immediately and again every time the bar moves the order on - accepted, preparing, ready, delivered, or declined with the reason on the next read. Open one per live order and close it when the order is delivered or declined. The publishable key and the token go in the query because EventSource cannot set headers; the seat stream uses the same key parameter.

Keyspk_sk_Scopebar

Parameters

idstring (path)required

The order id.

tokenstringrequired

The statusToken from the create response.

keystring (query)required

Your publishable key, in the query because EventSource cannot set headers. Never a secret key.

Returnsevent: status data: { status, updatedAt }

Read the enquiry form definition

Account owners can add their own enquiry fields in VenueSpine. Read the definition and render it, and your form keeps matching theirs without a redeploy.

Keyspk_sk_Scopeenquiries

Returns{ fields: EnquiryField[] }

Submit an enquiry

Writes straight into the sales pipeline. Secret key only, so it must be called from your server - never from the browser. Limited to 30 submissions a minute per key. The answer carries a url that opens the enquiry in VenueSpine for a signed-in member with access to the account’s enquiries: use it in your own staff alerts and keep it on your server.

Keyssk_Scopeenquiries

Body

contactNamestring 1-150required

Who is enquiring.

contactEmailstring email

Where the venue replies. Up to 180 characters.

contactPhonestring

A contact number. Up to 40 characters.

companyNamestring

Their company. Up to 150 characters.

eventNamestring

What they are planning. Up to 180 characters.

preferredDatestring YYYY-MM-DD

The date they would like.

alternativeDatestring YYYY-MM-DD

A second date that would also work.

guestCountinteger 1-100000

Expected guests.

budgetMinnumber

Lower end of the budget, in pounds.

budgetMaxnumber

Upper end of the budget, in pounds. Must be at least budgetMin when both are sent, or the answer is a 400 on budgetMax.

messagestring

The enquiry itself. Up to 5 000 characters.

fields{ [key]: string | number | boolean }

Values for the account’s custom fields, keyed by the field key from /enquiry-form. A key the account has not declared is still kept on the enquiry.

eventDetails{ label: string, value: string }[]

Facts about the event in your own words, such as { "label": "Start time", "value": "18:00" }, shown in order on the enquiry’s Event details card and its PDF. Up to 30 entries, labels up to 80 characters and values up to 1 000; an entry with an empty label or value is skipped. Use it for answers VenueSpine has no field for, and keep sending a real date as preferredDate. Each entry shows beside VenueSpine’s own fields, unless it repeats one of them that already has a value, so when you forward what a visitor typed, send only the labels your form uses. Enquiry triage reads the message and fields, not these entries.

marketingOptInboolean

True only when the person ticked your own marketing consent box. Adds them to the account’s Customers as opted in, with this enquiry as the proof.

hpstring

Honeypot. Leave it out of the form a person sees; any filled value is answered with a fake enquiry and nothing is saved. The fake answer looks real, url included, so skip your own staff alert when your form’s hidden field is filled.

Returns{ id: string, reference: string, url: string }

Create or link a customer

Mirror a person from your own sign-up into the account’s Customers. VenueSpine matches by your id first, then by email, then by phone digits, so a later email change still finds the same customer and a repeat call changes nothing. Matching is scoped to the key’s account: a record another account holds is never matched or named, and a conflict with one answers 409 CUSTOMER_UNAVAILABLE. Secret key only, called from your server once you have verified the person. Limited to 120 calls a minute per key.

Keyssk_Scopecustomers

Body

sourcestringrequired

A short name for your system ([a-z0-9._-], 2-60 chars). Scopes externalRef.

externalRefstringrequired

Your own id for the person. Never reused for anyone else.

firstNamestringrequired

Given name.

lastNamestring

Family name.

emailstring email

One of email or phone is required so the record can be matched to bookings.

phonestring

Matched on digits only.

consent{ optIn: boolean, proof?: string }

true subscribes the person to marketing with your proof text; false unsubscribes; omitted leaves consent alone.

sourceLabelstring

Shown as "created by" on a customer this call creates.

Returns{ customerId: string, reference: string, created: boolean, matchedBy: "externalRef" | "email" | "phone" | null }

List the services open to the website

The service windows the account takes web requests for - a lunch, a dinner - with the ISO weekdays they run on (1 is Monday), their hours, slot length, turn, largest party and deposit per head when one is set. A service the account has switched off, or has kept for the phone only, is left out.

Keyspk_sk_Scopereservations

Returns{ data: Service[] }

Open times for a date and party

Every slot on that date, per service, with whether it is open for a party of that size and how many seats are left. Capacity is the house floor plan: a slot is open when a free table seats the party for the whole turn. capacityKnown is false when the account has not drawn a floor yet, in which case every slot is open. A party above a service’s largest party shows every slot closed. Dates are the venue’s own: a date before its today is refused with RESERVATION_IN_PAST, and on its today a slot whose time has come is closed, with seatsLeft null.

Keyspk_sk_Scopereservations

Parameters

datestring YYYY-MM-DDrequired

The day to check: the venue’s today or later.

partyintegerrequired

How many guests.

servicestring

Restrict to one service.

Returns{ date, partySize, capacityKnown, services: [{ id, name, turnMinutes, maxPartySize, depositPerHead, slots: [{ time, available, seatsLeft }] }] }

Request a table

Lands in the account’s book as a request and is held for the service’s hold window until someone on the floor confirms it; a request nobody confirms in time is cancelled on its own. The guest becomes a customer on the account, matched by email and phone so a regular is not duplicated, and is emailed that the request is in, then again when the floor confirms or cancels it, so your site need not send its own. A publishable key must send a captchaToken from the Turnstile widget; a secret key from your server needs none. Three open requests per email at a time.

Keyspk_sk_Scopereservations

Body

serviceIdstringrequired

A service from GET /reservations/services.

datestring YYYY-MM-DDrequired

A day the service runs on: the venue’s today or later.

timestring HH:MMrequired

A slot the availability call marked open; on the venue’s today, one still to come.

partySizeintegerrequired

How many guests, up to the service’s largest party.

namestringrequired

Who the table is for.

emailstring emailrequired

Where the confirmation goes.

phonestring

A number the floor can reach them on.

notesstring

What the guest asked for - an occasion, a window seat, a high chair.

marketingOptInboolean

true subscribes the guest to marketing with the request as proof.

captchaTokenstring

Required with a publishable key: the token from the Turnstile widget.

hpstring

Honeypot. Leave it out of the form a person sees; a filled value is answered with a fake reference and nothing is booked.

Returns{ id, reference, status: "requested", date, time, partySize, serviceName, heldUntil }

Read a request by reference

The status of one request - requested, confirmed, seated, completed, no_show or cancelled - so your page can tell the guest the floor has confirmed it. Only the account the key belongs to can see its references.

Keyspk_sk_Scopereservations

Parameters

referencestring (path)required

The RSV- reference from the request.

Returns{ id, reference, status, date, time, partySize, serviceName, heldUntil }

Room types free for a set of nights

Every room type on sale that sleeps the party, with how many rooms are free for those nights, the nightly rate for each night from the account’s rate plans (the base rate where no plan covers a night), the total and the average. A type with nothing free is still listed with free: 0 so your page can say so.

Keyspk_sk_Scoperooms

Parameters

checkInstring YYYY-MM-DDrequired

The first night: the property’s today or later.

checkOutstring YYYY-MM-DDrequired

The morning the guest leaves; after checkIn and at most 365 nights on.

adultsinteger

How many adults (default 2).

childreninteger

How many children (default 0). Adults plus children must fit what the type sleeps.

Returns{ checkIn, checkOut, nights, guests, roomTypes: [{ id, name, description, sleeps, capacity, free, nights, nightly: number[], total, averageRate }] }

Book a room type for the nights

Lands on the account’s tape chart as reserved, priced from the rate plans at the moment of booking, with a STY- reference. The desk assigns the room at check-in. The guest becomes a customer on the account, matched by email and phone so a regular is not duplicated, and is emailed the booking (and later any cancellation and the check-out summary), so your site need not send its own. A publishable key must send a captchaToken from the Turnstile widget; a secret key from your server needs none. Three open stays per email at a time.

Keyspk_sk_Scoperooms

Body

roomTypeIdstringrequired

A room type from GET /rooms/availability with rooms free.

checkInstring YYYY-MM-DDrequired

The first night: the property’s today or later.

checkOutstring YYYY-MM-DDrequired

The morning the guest leaves, at most 365 nights after checkIn.

adultsinteger

How many adults (default 2).

childreninteger

How many children (default 0).

namestringrequired

Who is staying.

emailstring emailrequired

Where the confirmation goes.

phonestring

A number the desk can reach them on.

notesstring

What the guest asked for - a cot, a late arrival, a quiet room.

marketingOptInboolean

true subscribes the guest to marketing with the booking as proof.

captchaTokenstring

Required with a publishable key: the token from the Turnstile widget.

hpstring

Honeypot. Leave it out of the form a person sees; a filled value is answered with a fake reference and nothing is booked.

Returns{ id, reference, status: "reserved", checkIn, checkOut, nights, roomTypeName, guestName, total }

Read a stay by reference

The status of one stay - reserved, checked_in, checked_out, no_show or cancelled - with its nights and total. Only the account the key belongs to can see its references.

Keyspk_sk_Scoperooms

Parameters

referencestring (path)required

The STY- reference from the booking.

Returns{ id, reference, status, checkIn, checkOut, nights, roomTypeName, guestName, total }