Check availability

POST

/public/v1/availability/search

const url = 'https://example.kwickbooking.com/public/v1/availability/search';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"venueId":"01920000-0000-7000-8000-000000000001","date":"2026-10-16","time":"20:00","partySize":6,"acrossVenues":false}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.kwickbooking.com/public/v1/availability/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "venueId": "01920000-0000-7000-8000-000000000001", "date": "2026-10-16", "time": "20:00", "partySize": 6, "acrossVenues": false }'

Answers what is free for a party on a date, or at a time: each free time with the booking types, lengths and deposits that fit it. When the asked time is taken it offers the nearest times, then the next days, and with acrossVenues the key’s other venues. Dates are venue-local yyyy-MM-dd and times HH:mm.

Authorizations

IntegrationKey

Request Body^required

application/json

POST /public/v1/availability/search: what is free for PartySize on Date (venue-local yyyy-MM-dd), optionally at Time (HH:mm). A multi-venue key names the venue; AcrossVenues also looks at the key’s other venues.

object

venueId

required

null | string format: uuid

date

required

string

time

required

null | string

partySize

required

integer format: int32

bookingTypeId

null | string format: uuid

acrossVenues

boolean

Example

{
  "venueId": "01920000-0000-7000-8000-000000000001",
  "date": "2026-10-16",
  "time": "20:00",
  "partySize": 6,
  "acrossVenues": false
}

Responses

200

application/json

The answer to an availability check, with a summary to read out.

object

venueId

required

string format: uuid

date

required

string

partySize

required

integer format: int32

outcome

required

string

times

required

Array<object>

A free time (venue-local HH:mm) and the booking types that fit it.

object

time

required

string

options

required

Array<object>

A booking type that fits a time, with its length and deposit.

object

bookingTypeId

required

string format: uuid

bookingType

required

string

durationMinutes

required

integer format: int32

deposit

required

A deposit as a guest would hear it.

object

required

required

boolean

amountPence

required

integer format: int32

amountDisplay

required

null | string

alternatives

required

Array<object>

Another time, day or venue that fits when the asked one doesn’t.

object

venueId

required

string format: uuid

venueName

required

string

date

required

string

time

required

string

options

required

Array<object>

A booking type that fits a time, with its length and deposit.

object

bookingTypeId

required

string format: uuid

bookingType

required

string

durationMinutes

required

integer format: int32

deposit

required

A deposit as a guest would hear it.

object

required

required

boolean

amountPence

required

integer format: int32

amountDisplay

required

null | string

summary

required

string

Example

{
  "venueId": "01920000-0000-7000-8000-000000000001",
  "date": "2026-10-16",
  "partySize": 6,
  "outcome": "available",
  "times": [
    {
      "time": "20:00",
      "options": [
        {
          "bookingTypeId": "01920000-0000-7000-8000-000000000003",
          "bookingType": "Table booking",
          "durationMinutes": 120,
          "deposit": {
            "required": false,
            "amountPence": 0,
            "amountDisplay": null
          }
        }
      ]
    }
  ],
  "alternatives": [],
  "summary": "Fri 16/10 at 20:00 is free for 6"
}

400

Venue required (https://developers.kwickblocks.ai/problems/venue-required); Validation failed (https://developers.kwickblocks.ai/problems/validation-failed)

application/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object

type

required

string format: uri

title

required

string

status

required

integer format: int32

detail

required

Safe to read to a guest.

string

instance

string

traceId

string

code

A machine-readable code on the widget’s routes.

string

Examples

Venue required

{
  "type": "https://developers.kwickblocks.ai/problems/venue-required",
  "title": "Venue required",
  "status": 400,
  "detail": "Please say which venue this is for."
}

Validation failed

{
  "type": "https://developers.kwickblocks.ai/problems/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "Some of the details weren't valid. Please check them and try again."
}

401

Invalid or missing integration key (https://developers.kwickblocks.ai/problems/invalid-key)

application/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object

type

required

string format: uri

title

required

string

status

required

integer format: int32

detail

required

Safe to read to a guest.

string

instance

string

traceId

string

code

A machine-readable code on the widget’s routes.

string

Examples

invalid-key

Invalid or missing integration key

{
  "type": "https://developers.kwickblocks.ai/problems/invalid-key",
  "title": "Invalid or missing integration key",
  "status": 401,
  "detail": "This integration key isn't valid. Ask the venue's admin for a new one."
}

403

Capability not granted (https://developers.kwickblocks.ai/problems/capability-missing)

application/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object

type

required

string format: uri

title

required

string

status

required

integer format: int32

detail

required

Safe to read to a guest.

string

instance

string

traceId

string

code

A machine-readable code on the widget’s routes.

string

Examples

capability-missing

Capability not granted

{
  "type": "https://developers.kwickblocks.ai/problems/capability-missing",
  "title": "Capability not granted",
  "status": 403,
  "detail": "This integration key isn't allowed to do that. Ask the venue's admin to add the capability."
}

404

Venue not found (https://developers.kwickblocks.ai/problems/venue-not-found)

application/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object

type

required

string format: uri

title

required

string

status

required

integer format: int32

detail

required

Safe to read to a guest.

string

instance

string

traceId

string

code

A machine-readable code on the widget’s routes.

string

Examples

venue-not-found

Venue not found

{
  "type": "https://developers.kwickblocks.ai/problems/venue-not-found",
  "title": "Venue not found",
  "status": 404,
  "detail": "I couldn't find that venue."
}

429

Too many requests (https://developers.kwickblocks.ai/problems/rate-limited)

application/problem+json

RFC 9457 problem details. type is a URI with a page describing the problem.

object

type

required

string format: uri

title

required

string

status

required

integer format: int32

detail

required

Safe to read to a guest.

string

instance

string

traceId

string

code

A machine-readable code on the widget’s routes.

string

Examples

rate-limited

Too many requests

{
  "type": "https://developers.kwickblocks.ai/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "There have been too many requests. Please try again in a minute."
}

Check availability

Authorizations

Request Bodyrequired

Example

Responses

200

Example

400

Examples

401

Examples

403

Examples

404

Examples

429

Examples

Request Body^required