Reservations

List bookable times

The venue's booking calendar: the days asked for, each with the times still bookable.

GET/public/v1/venues/{venueId}/reservation-availability

Authentication: An API key in the X-Api-Key header
Permission: Can take reservations
Rate limit: About 120 requests a minute per key

Returns the venue's booking calendar, a day at a time. It is the calendar the venue's own booking page on cibusy.com shows, worked out by the rules a booking is held to, so a time listed here is a time taking a reservation accepts. Show the guest a slot's time, which is on the venue's own clock, and send its startsAt.

Slots are half an hour apart, within the hours the venue takes bookings in: its working hours, or the booking hours it narrowed them to. None is less than minNoticeMinutes away or past lastBookableDate. A venue that seats past midnight lists those late times under the evening they belong to. A day reads Closed when the venue is shut and HoursUnknown when it has entered no working hours for that weekday; neither has slots.

reservationsEnabled is false for a venue that has switched bookings off: days is then empty and a booking is refused. confirmsAutomatically says what a new booking will be: Confirmed at once, or Pending until the venue answers.

The calendar says when the venue seats, not how full it is: Cibusy does not count tables, and the venue declines a request it has no room for.

Guide: Taking reservations

Parameters

venueIdstring · uuidPath parameterrequired

The venue, one of the ids GET /venues lists.

fromstringQuery parameter

The first day wanted, on the venue's calendar, as yyyy-MM-dd. The venue's today when left out or earlier than it.

daysintegerQuery parameter

How many days: 7 when left out, and never more than 14 however many are asked for.

Accept-LanguagestringHeader

The language of userMessage in an error: tr (the default), en, de, fr, it, es, ar or ru. The first language in the header decides, without its region (en-US reads as en) and without weighing q values; a language Cibusy does not offer is answered in Turkish. It does not choose the language of a menu: that is lang on the menu call.

Responses

200

The venue's booking calendar.

401

The X-Api-Key header is missing (PUBLIC_API_KEY_MISSING), or the key is invalid or has been revoked (PUBLIC_API_KEY_INVALID).

403

PUBLIC_API_SCOPE_MISSING: the key was not made with the "Can take reservations" permission.

404

The venue does not exist, or this key cannot reach it (PUBLIC_API_VENUE_NOT_FOUND).

429

The key's budget of about 120 requests a minute is spent; wait Retry-After seconds.

Retry-After

Seconds to wait. The next one-minute window opens within it.

The `data` of a successful answer

The times a venue can be booked at, day by day, and the rules a booking is held to. The same calendar the venue's own booking page on cibusy.com shows, so a time listed here is a time taking a reservation accepts.

venueIdstring · uuid

The venue.

reservationsEnabledboolean

Whether the venue takes bookings at all. When it is false, days is empty and a booking is refused with RESERVATIONS_DISABLED.

confirmsAutomaticallyboolean

Whether the venue confirms a booking as it is made. When it is false, a new booking is Pending until the venue answers it.

timeZonestring

The IANA name of the venue's time zone: whose clock each slot's time is on.

maxGuestsinteger

The largest party that can be booked through the API. A larger one calls the venue.

minNoticeMinutesinteger

How many minutes ahead a booking has to be made, at the least.

lastBookableDatestring

The last date, on the venue's calendar, a table can be booked for.

daysobject[]

The days asked for, in order. Empty when the venue takes no bookings.

Fields of Calendar day

datestring

The date, on the venue's calendar. A venue that seats past midnight lists those late times under the evening they belong to.

statestring

Whether tables can be booked on this day.

Open: The venue takes bookings on this day. Its `slots` are the times still bookable.
Closed: The venue is shut: its day off, or a date it marked as closed.
HoursUnknown: The venue has entered no working hours for this weekday, so no time can be offered on it.

slotsobject[]

The times still bookable, earliest first. Empty unless the day is Open.

Fields of Bookable time

startsAtstring · date-time

The time as an instant in UTC: what to send as startsAt.

timestring

The same time on the venue's own clock, HH:mm: what to show the guest.

Request sample

curl "https://api.cibusy.com/public/v1/venues/3fa85f64-5717-4562-b3fc-2c963f66afa6/reservation-availability?from=2026-10-09&days=3" \
  -H "X-Api-Key: $CIBUSY_API_KEY"

Response sample

200 OK

{
  "success": true,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "data": {
    "venueId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reservationsEnabled": true,
    "confirmsAutomatically": false,
    "timeZone": "Europe/Istanbul",
    "maxGuests": 20,
    "minNoticeMinutes": 30,
    "lastBookableDate": "2026-11-30",
    "days": [
      {
        "date": "2026-10-09",
        "state": "Open",
        "slots": [
          {
            "startsAt": "2026-10-09T16:00:00.000Z",
            "time": "19:00"
          },
          {
            "startsAt": "2026-10-09T16:30:00.000Z",
            "time": "19:30"
          },
          {
            "startsAt": "2026-10-09T17:00:00.000Z",
            "time": "20:00"
          },
          {
            "startsAt": "2026-10-09T17:30:00.000Z",
            "time": "20:30"
          }
        ]
      },
      {
        "date": "2026-10-10",
        "state": "Open",
        "slots": [
          {
            "startsAt": "2026-10-10T16:00:00.000Z",
            "time": "19:00"
          },
          {
            "startsAt": "2026-10-10T16:30:00.000Z",
            "time": "19:30"
          }
        ]
      },
      {
        "date": "2026-10-11",
        "state": "Closed",
        "slots": []
      }
    ]
  },
  "message": "Operation completed successfully"
}

Error sample

404 Not Found

{
  "success": false,
  "userMessage": "Venue not found, or this API key cannot access it.",
  "developerMessage": "Venue not found, or this API key cannot access it.",
  "errorCode": "PUBLIC_API_VENUE_NOT_FOUND",
  "validationErrors": null,
  "details": null,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null
}

List bookable times

Parameters

Responses

The data of a successful answer

The `data` of a successful answer