Version 1. Access via an individual business key.

The TGbot Cafe booking calendar API returns busy intervals for all halls connected to a business. A website or another application can use them to display an availability calendar. This is a read-only method: it does not support creating or modifying bookings, taking payments or reserving time. Responses exclude customer names and phone numbers, comments, services, amounts and internal document numbers.

Download the OpenAPI 3.0.3 contract

Method and access

The API administrator issues the key after connecting the business. Its format is the prefix arma_avail_ followed by 64 hexadecimal characters. This is a separate TGbot Cafe key; AssistBot messaging API tokens do not work for this method. One key opens only the assigned business's calendar and does not grant access to the admin panel or payment operations.

Send HTTPS requests from your application's server. Store the key in a private server configuration; do not include it in HTML, browser JavaScript or the request URL. If it is exposed, ask the administrator to revoke it and issue a new one. The key determines the business; query parameters cannot change it.

Query parameters

• RFC3339 with whole seconds and an explicit time zone is required: an offset, for example +03:00, or Z. The maximum offset is ±14:00. Fractional seconds, dates without a time and times without a time zone are not accepted.
• The range is expressed as [from, to): the start is inclusive and the end exclusive. The end must be later than the start, with a duration no greater than 31 × 24 hours, or 2 678 400 seconds.
• Only the following are allowed: from and to. Selecting a business or filtering halls is not supported: the response includes all configured halls for the business.
• Encode the + character as %2B. Use a query builder or --data-urlencode.

Example for a connected business. The variable AVAILABILITY_KEY contains the issued key:

curl --fail-with-body --get 'https://tgbotcafe.assistbot.ru/api/v1/availability' \
  --header "Authorization: Bearer ${AVAILABILITY_KEY}" \
  --header 'Accept: application/json' \
  --data-urlencode 'from=2026-10-15T00:00:00+03:00' \
  --data-urlencode 'to=2026-10-17T00:00:00+03:00'

Response and example

A fictional example of a business with six halls. Other connections may have different hall lists and codes. The first booking crosses midnight:

{
  "version": 1,
  "source": "admin_calendar",
  "timezone": "Europe/Moscow",
  "from": "2026-10-15T00:00:00+03:00",
  "to": "2026-10-17T00:00:00+03:00",
  "generated_at": "2026-10-13T13:20:00+03:00",
  "data_updated_at": "2026-10-13T12:45:00+03:00",
  "freshness": "live",
  "complete": false,
  "incomplete_reasons": ["calendar_not_authoritative"],
  "halls": [
    {"hall_id": "armaloft", "name": "ArmaLoft Hall", "busy_intervals": [
      {"starts_at": "2026-10-15T22:00:00+03:00", "ends_at": "2026-10-16T02:00:00+03:00"}
    ]},
    {"hall_id": "mercury", "name": "Mercury Hall", "busy_intervals": []},
    {"hall_id": "airplane", "name": "Airplane Hall", "busy_intervals": []},
    {"hall_id": "rufer", "name": "Rufer Hall", "busy_intervals": []},
    {"hall_id": "pulka", "name": "Pulka Hall", "busy_intervals": []},
    {"hall_id": "boho", "name": "Boho Hall", "busy_intervals": []}
  ]
}

How to determine available times

When complete=false the absence of a busy interval does not mean a hall is available: some bookings may still exist in an external source. You can mark known busy periods but cannot confirm availability for the remaining hours. Even HTTP 200 and an empty array do not confirm availability in this case.

Before displaying available times, check HTTP 200, version=1, source=admin_calendar, freshness=live, complete=true and the complete expected list of halls. In case of an error or incomplete calendar, display “Availability temporarily unconfirmed”; do not substitute an empty calendar for that response.

• Busy intervals are sorted; overlapping and adjacent intervals are merged. Original boundaries are retained even if a booking starts before from or ends after to.
• A booking is included when starts_at < to and ends_at > from. An adjacent booking may start exactly when the preceding one ends.
• Cancelled bookings are excluded. A no-show, lack of payment or a free viewing does not by itself release the time. Minutes and overnight intervals are preserved without rounding to hours.

Method responses include the directive no-store in the Cache-Control, for example no-store, private; the header may contain additional valid directives. Do not cache responses as confirmed availability. One request is enough for all halls. Reading the calendar does not reserve the selected time: another user may create a booking after the response. The method does not synchronize external calendars or automatically replace the existing booking creation process.

Errors

Authorization, parameter and calendar reading errors return a short JSON response:

{"error":{"code":"calendar_unavailable"}}

Any other response, including 500, also does not confirm availability. Standard 405 and 429 responses are not guaranteed to follow the calendar error format. HEAD is allowed with the same authorization and headers and no body; it is not a separate second API method.