Get canonical availability slots

GET /availability/get/

What It Does

Return the canonical slots that TheBooking considers bookable for a service, provider, and time range.

Authentication

Requires an API token with the read scope. Send it as a bearer token or with the configured API key header.

Parameters

Name	Location	Required	Type	Description
min_timestamp	query	Yes	integer (int64)	Unix timestamp for the beginning of the availability window.
max_timestamp	query	Yes	integer (int64)	Unix timestamp for the end of the availability window.
services	query	No	string	Comma-separated service IDs.
providers	query	No	string	Comma-separated provider IDs.
limit	query	No	integer	Candidate times to evaluate in this page (800 by default). It limits the work per request, not the number of slots returned. 0 evaluates every candidate in one request.
offset	query	No	integer	Where the page starts. Send pagination.next_offset of the previous page.
cursor	query	No	string	Send pagination.next_cursor of the previous page, when present. If it is missing or expired, the page starts from offset.

Request Body

This endpoint does not require a JSON request body.

Responses

Status	Meaning	Description	Body
200	Success	One page of available slots	OkEnvelope + object
401	Authentication required	Missing or invalid API token	WpRestError

Booking Rules

• Always query availability before creating or rescheduling a reservation.
• Treat the returned slot data as a short-lived booking token: send the same availabilityId, serviceId, providerId, start, and end values when creating the reservation.
• The response is paginated: while pagination.has_more is true, repeat the request with offset and cursor from pagination. A page can contain few slots, or none, and still have more pages.

Request Example

curl -X GET "https://example.com/wp-json/thebooking/v1/API/availability/get/?min_timestamp=1779148800&max_timestamp=1779753600&services=service_123&providers=123" \
  -H "Authorization: Bearer $TBK_API_TOKEN"

Success Response Example

{
  "status": "OK",
  "response": [
    {
      "availabilityId": "slot_123",
      "serviceId": "service_123",
      "providerId": 123,
      "start": 1779148800,
      "end": 1779152400,
      "bookable": true,
      "routingMode": "manual",
      "eligibleProviderIds": [
        123
      ],
      "reservationsCount": 1,
      "overrides": {}
    }
  ],
  "pagination": {
    "has_more": true,
    "next_offset": 800,
    "next_cursor": "opaque-cursor-value",
    "processed_count": 800,
    "total_candidates": 2150
  }
}