Documentation

Availability API

Table of Contents

Overview

The reservation availability endpoint performs a batch availability check for one or more resources across one or more requested time windows.

It is useful for:

  • Checking whether a set of resources can all be reserved at the same time
  • Looking up availability for multiple candidate time slots in one request
  • Getting the number of units currently available for each requested resource

This endpoint is an authenticated pre-check only. It does not create or hold a reservation.

Note

All requested resources must belong to the same site, and the authenticated user must belong to that site.

Request Body Structure

{
    "for_reservables": [
        {
            "reservable_id": "string",
            "units": integer,
            "named_unit_id": "string"
        }
    ],
    "for_times": [
        {
            "start": "string",
            "duration": integer
        }
    ]
}

Fields

Field Type Required Description
for_reservables array Yes List of resources to check. Must contain at least one item.
for_times array Yes List of time windows to check. Must contain at least one item.

for_reservables Items

Field Type Required Description
reservable_id string Yes ID of the resource to check
units integer Yes Number of units requested for that resource
named_unit_id string No Specific named unit to check

for_times Items

Field Type Required Description
start string Yes Start of the requested timespan
duration integer Yes Duration in seconds

Note

start is interpreted in the site timezone of the requested resources. The parser accepts several date formats, including YYYY-MM-DDTHH:MM:SS, YYYY-MM-DD HH:MM:SS, YYYY-MM-DD, and unix timestamps. Use a full datetime string to avoid ambiguity.

Response Data Structure

The standard QReserve API response wraps the result list in the root data field. Each item in data corresponds to one item from for_times.

{
    "start": "string",
    "duration": integer,
    "available": [
        {
            "reservable_id": "string",
            "units": integer
        }
    ]
}

Fields

Field Type Description
start string Echo of the requested start value
duration integer Echo of the requested duration in seconds
available array Per-resource availability results for that time window

available Items

Field Type Description
reservable_id string Resource ID
units integer Number of units currently available for that resource during the requested timespan

Check Reservation Availability

POST /reservation/availability

Authentication

This endpoint requires an authenticated user session or API authentication that resolves to a user.

Request Body

Required Fields

Field Type Required Description
for_reservables array Yes One or more resources to check
for_times array Yes One or more time windows to check

Required for_reservables Item Fields

Field Type Required Description
reservable_id string Yes Resource ID
units integer Yes Number of units requested

Optional for_reservables Item Fields

Field Type Default Description
named_unit_id string Specific named unit to test

Required for_times Item Fields

Field Type Required Description
start string Yes Requested start datetime
duration integer Yes Requested duration in seconds

Example Request

{
    "for_reservables": [
        {
            "reservable_id": "rhy58opa5kewizwy7fozlbyvhdwrbcdu6jd60",
            "units": 1
        },
        {
            "reservable_id": "hedrchelt0xf04uf0uze5wnb27ntra3rwjnrh",
            "units": 1
        }
    ],
    "for_times": [
        {
            "start": "2026-03-20T09:00:00",
            "duration": 3600
        },
        {
            "start": "2026-03-20T13:00:00",
            "duration": 3600
        }
    ]
}

Example Success Response

{
    "api_version": 1,
    "status": "success",
    "action": "unknown",
    "numitems": 2,
    "data": [
        {
            "start": "2026-03-20T09:00:00",
            "duration": 3600,
            "available": [
                {
                    "reservable_id": "rhy58opa5kewizwy7fozlbyvhdwrbcdu6jd60",
                    "units": 1
                },
                {
                    "reservable_id": "hedrchelt0xf04uf0uze5wnb27ntra3rwjnrh",
                    "units": 1
                }
            ]
        },
        {
            "start": "2026-03-20T13:00:00",
            "duration": 3600,
            "available": [
                {
                    "reservable_id": "rhy58opa5kewizwy7fozlbyvhdwrbcdu6jd60",
                    "units": 0
                },
                {
                    "reservable_id": "hedrchelt0xf04uf0uze5wnb27ntra3rwjnrh",
                    "units": 0
                }
            ]
        }
    ]
}

Error Cases

Status Code Condition
400 Body is missing or is not valid JSON
403 Resources span more than one site
403 Authenticated user is not a member of the inferred site
404 One or more reservable_id values could not be found
422 Request body is missing required fields or contains invalid values

Notes

  • The site is inferred from the requested resources. There is no site_id parameter on this endpoint.
  • Availability is evaluated in the site timezone of the requested resources.
  • The response is organized by requested time window, not by resource.
  • This endpoint returns available unit counts only. It does not return detailed conflict metadata.
  • If any requested resource fails the availability check for a given time window, the endpoint returns 0 units for the resources in that row.