Skip to content

Quickstart

Get a sandbox key, read your venue and create your first booking in five minutes.

The Boozie API lets your software read a venue's tables, sessions and menu, take bookings, run the guest list and receive webhooks. This guide gets you from nothing to a booking on the sandbox in about five minutes.

1. Get a sandbox key#

Ask for a key with the form on the developer portal, or call the API yourself:

curl -X POST https://api-dev-799b.up.railway.app/public/v1/sandbox/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "My booking widget"}'

The answer is 202 Accepted:

{
  "status": "accepted",
  "message": "If this address can get a sandbox key, it is on its way. Check your inbox (and spam folder) in a few minutes.",
  "venueId": 0,
  "expiresInDays": 30
}

The key itself arrives by email, with the id of your own sandbox venue: every address gets a venue of its own, made with its first key. (venueId in the answer is always 0; it is deprecated.) The key looks like bz_test_ab12cd34_…, works on your sandbox venue only and expires in 30 days. Keep it secret: anyone with the key can act as your integration.

For your own venue, a venue owner makes keys in the back office under Developers (only owners see it). Those keys can be limited to a few scopes, and live keys work on production.

2. Set up your shell#

export BOOZIE_API=https://api-dev-799b.up.railway.app/public/v1
export BOOZIE_KEY=bz_test_…   # from the email
export VENUE=7                # your sandbox venue's id, from the email

Every request sends the key as a bearer token. First, list the venues the key covers (a sandbox key covers one, your sandbox venue, so this is also where to find its id):

curl $BOOZIE_API/venues -H "Authorization: Bearer $BOOZIE_KEY"

The venue is always in the path, as /venues/{venueId}/…; there is no venue header. Fetch the sandbox venue:

curl $BOOZIE_API/venues/$VENUE \
  -H "Authorization: Bearer $BOOZIE_KEY"

You get the venue: its name (qa-sandbox Lounge), currency, time zone, booking settings and rating.

3. Look at the tables and the night's availability#

curl "$BOOZIE_API/venues/$VENUE/tables" -H "Authorization: Bearer $BOOZIE_KEY"

curl "$BOOZIE_API/venues/$VENUE/availability?date=2026-11-20&partySize=4" \
  -H "Authorization: Bearer $BOOZIE_KEY"

Use a date in the next two weeks. Availability lists the night's sessions, and in each the tables that are free and seat your party:

{
  "date": "2026-11-20",
  "bookable": true,
  "currency": "SGD",
  "sessions": [
    {
      "sessionId": 31,
      "startsAt": "2026-11-20T21:00:00+08:00",
      "endsAt": "2026-11-20T23:59:00+08:00",
      "featured": false,
      "featuredNote": "",
      "tables": [{ "tableId": 104, "name": "T1", "capacity": 6, "minPax": null, "…": "…" }]
    }
  ]
}

A night runs past midnight: the 00:00–03:00 session belongs to the night before, as it does at a real venue. Ids change every time the sandbox resets, so look them up instead of hard-coding them.

4. Make a booking#

Pick a session's startsAt and endsAt and one of its tables. Writes need an Idempotency-Key, so a retry after a network error can't book twice:

curl -X POST "$BOOZIE_API/venues/$VENUE/bookings" \
  -H "Authorization: Bearer $BOOZIE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tableId": 104,
    "startsAt": "2026-11-20T21:00:00+08:00",
    "endsAt": "2026-11-20T23:59:00+08:00",
    "pax": 4,
    "remark": "Birthday, a cake at 22:00",
    "contact": { "name": "Test Guest", "phone": "+6555500999" }
  }'

The answer is 201 with the booking. The sandbox venue confirms bookings by hand, so it starts pending. On the sandbox a pending booking expires after 24 hours (at real venues, 30 minutes). Confirm it as the venue would:

curl -X POST "$BOOZIE_API/venues/$VENUE/bookings/<bookingId>/confirm" \
  -H "Authorization: Bearer $BOOZIE_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Use made-up people only. The sandbox is shared: other developers see your bookings, and you'll see theirs.

5. Next steps#

  • Try every endpoint from the browser in the API reference. It sends requests to the sandbox with your key.
  • Register a webhook to hear about new bookings instead of polling.
  • Read the conventions (times, money, paging, retries) and the errors before you go live.
  • Building one integration for many venues? Read OAuth apps. One company with many venues? Read Organisations.
  • Generate a client from the OpenAPI 3.1 spec at https://api-dev-799b.up.railway.app/public/v1/openapi.json, for example with npx openapi-typescript https://api-dev-799b.up.railway.app/public/v1/openapi.json -o boozie.ts.

Next: Authentication