Booking resources

GET /v1/booking-resources

Returns the booking resources available to the key. This is the only way to learn the values for the mandatory resourceIds field when creating a booking — start here if you are creating your first booking.

The method returns the whole catalogue at once and accepts no pagination parameters: meta.total always equals the length of data, and meta.hasMore is always false.

Parameters

The parameters may be combined. Any other parameter, a repeated parameter, an array or object spelling (typeId[], filter[typeId]) is rejected with 400 INVALID_PARAMS before Bitrix24 is contacted.

Sorting is deliberately not exposed: the walk always goes by ascending id, and a caller-controlled order would break the completeness guarantee of the response.

Examples

curl — personal key

curl "https://vibecode.bitrix24.com/v1/booking-resources?typeId=1" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/booking-resources" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — from the resource list to a booking

const res = await fetch('https://vibecode.bitrix24.com/v1/booking-resources?searchQuery=meeting', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log(`Resources available: ${data.length}`)

const room = data.find(r => r.isMain === 'Y') ?? data[0]

await fetch('https://vibecode.bitrix24.com/v1/bookings', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    resourceIds: [room.id],
    datePeriod: {
      from: { timestamp: 1723446900, timezone: 'Europe/Berlin' },
      to: { timestamp: 1723447800, timezone: 'Europe/Berlin' },
    },
  }),
})

Response fields

The description field is withheld deliberately: it is free-form portal text that may contain personal data and internal notes, and it is not needed to pick a resource. Notification and template settings are not returned either.

The response carries the Cache-Control: private, no-store header — the content is bound to the Bitrix24 account and to the identity of the key.

Response example

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Meeting room for 6",
      "typeId": 1,
      "isMain": "Y"
    },
    {
      "id": 3,
      "name": "Meeting room with a projector",
      "typeId": 1,
      "isMain": "N"
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Error response example

400 — an unknown parameter was passed:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Only typeId and searchQuery are supported query parameters."
  }
}

Errors

No refusal contains partially collected data: the response is either complete or an error.

The full list of common API errors — Errors.

Known specifics

The catalogue cap is 500 resources. An account with more resources gets 502 BITRIX_RESULT_TOO_LARGE instead of a truncated list: handing back the first 500 as the whole catalogue would be a lie. Narrow the lookup with the filters.

Completeness is guaranteed for a catalogue that did not change during the request. Bitrix24 provides no snapshot of the collection, so creating or deleting a resource while the walk is in progress can shift a page. The response then stays well-formed but may omit a just-created resource or still contain a just-deleted one.

Visibility is decided by Bitrix24. The method returns what the account shows to the identity behind the key. An employee key with the booking scope may call the method; whether its list matches an administrator's is decided by Bitrix24, not by the platform.

A read-only key works. The method is a read, so read-only mode does not refuse it. The limit of 20 requests per minute per Bitrix24 account still applies to every key.

See also

• Bookings
• Create a booking
• List bookings
• Errors
• Limits and optimization