Booking Calendars

Retrieve booking-focused calendar data and occupancy counts for display in calendar UIs. This endpoint belongs to the Bookings surface, even though the aggregate route itself lives in the misc path file. For general conventions, see JSON-API Conventions. For availability search, see Availability & Booking Search.

Prerequisites

At least one resource with a configured schedule
Public endpoint — no authentication required for basic usage

Unified Calendar View

Request path documentation:

paths/public/misc.yaml for GET /api/v1/calendar-events

The main endpoint aggregates multiple data sources into a single response:

GET /api/v1/calendar-events?resource_id={resource_uuid}&start_date=2026-04-01T00:00:00Z&end_date=2026-04-30T23:59:59Z

Parameters

Parameter	Type	Required	Description
`resource_id`	string/array	Yes	Single UUID or array of resource UUIDs
`start_date`	string	No	Range start (ISO 8601). Defaults to current time.
`end_date`	string	No	Range end (ISO 8601)
`timezone`	string	No	Timezone for local date calculations (e.g. `Europe/Berlin`)
`filter[exclude_child_resources]`	boolean	No	Only show parent resource data

Multiple Resources

Query multiple resources in a single request:

GET /api/v1/calendar-events?resource_id[]={uuid_1}&resource_id[]={uuid_2}&start_date=2026-04-01T00:00:00Z

Event Types

The response contains events of different types, combined from booking and availability data sources:

Type	Description
`period`	A raw availability slot from the resource’s schedule
`period_fragment`	Remaining availability after bookings are subtracted
`booking`	An accepted booking (includes customer data for small-capacity resources)
`reserved_booking`	A temporary hold — no customer details exposed
`blocker`	A manually blocked time slot included in the aggregated calendar response
`booking_count`	Aggregated booking count for high-capacity resources (>25 slots)

Response Structure

{
  "data": {
    "events": [
      {
        "id": "event-uuid",
        "type": "booking",
        "timeslot_id": "9a93435a-86b2-449f-85ef-d47d477b9abe",
        "title": "Session 1",
        "start_date": "2026-04-15T10:00:00Z",
        "end_date": "2026-04-15T11:00:00Z",
        "resource_id": "res-uuid",
        "resource_name": "Meeting Room A",
        "resource_info": [
          {
            "id": 15,
            "name": "Projector",
            "slug": "projector",
            "category_name": "Equipment"
          }
        ],
        "quota": 1,
        "occupancy": 1.0,
        "is_available": false,
        "is_blocker": false,
        "display_label": "Jane Doe - Workshop",
        "customers": [
          { "id": "cust-1", "first_name": "Jane", "last_name": "Doe" }
        ],
        "bookings": [
          { "id": "book-uuid", "status": "accepted" }
        ],
        "color_map": { "bg": "#3b82f6", "text": "#ffffff" }
      },
      {
        "id": "period-uuid",
        "type": "period_fragment",
        "start_date": "2026-04-15T11:00:00Z",
        "end_date": "2026-04-15T18:00:00Z",
        "resource_id": "res-uuid",
        "is_available": true,
        "quota": 1,
        "occupancy": 0.0
      }
    ],
    "resources_with_schedule": ["res-uuid"]
  }
}

Timeslot-backed events can include timeslot_id. Use it to fetch the canonical timeslot resource through the admin timeslot endpoints, open the matching editor, or reconcile calendar cards with resource_info and allocation state.

Capacity-Based Rendering

The API adapts its response based on resource capacity:

Small resources (capacity ≤ 25): Returns individual booking events with customer details. Use these to render detailed calendar entries.
Large resources (capacity > 25): Returns booking_count events with aggregated occupancy numbers. Use these for heatmap or occupancy bar display.

Booking Detail Preview

For calendar detail views, use the booking preview endpoint to get a summary of a specific booking without fetching the full resource:

GET /api/v1/customer-accounts/{account_id}/booking-preview/{booking_id}

Common Patterns

Daily Calendar View

GET /api/v1/calendar-events?resource_id={uuid}&start_date=2026-04-15T00:00:00Z&end_date=2026-04-15T23:59:59Z&timezone=Europe/Berlin

Weekly Multi-Resource View

GET /api/v1/calendar-events?resource_id[]={uuid_1}&resource_id[]={uuid_2}&start_date=2026-04-14T00:00:00Z&end_date=2026-04-20T23:59:59Z

Correlate a Calendar Event to Timeslot CRUD

When an event includes timeslot_id, you can jump from the aggregate calendar response to the admin timeslot resource:

GET /api/v1/timeslots/{timeslot_id}?include=resource,series,resource_allocations.resource

For the full admin workflow, see Admin Timeslot Management.

Common Errors

Error	Cause	Solution
Empty `events` array	Resource has no schedule configured	Verify the resource has an active schedule
Missing customer data	High-capacity resource	Use `booking_count` events instead of individual bookings
`422` — resource_id required	Missing parameter	Always include at least one `resource_id`

​Prerequisites

​Unified Calendar View

​Parameters

​Multiple Resources

​Event Types

​Response Structure

​Capacity-Based Rendering

​Booking Detail Preview

​Common Patterns

​Daily Calendar View

​Weekly Multi-Resource View

​Correlate a Calendar Event to Timeslot CRUD

​Common Errors