Skip to main content
Read calendar events and manage bookings, recurring bookings, calendar tasks, booking requests, and availability settings. Calendar events themselves are read-only in Public API v1. To book a slot, list bookable availability, then create a booking with its availabilityToken. Send Authorization: Bearer <access_token> with every request. Write requests also require an Idempotency-Key. See the idempotency contract for retry rules.

Lesson capacity

Capacity uses the first positive limit in this order: the occurrence override, the recurring-series override, then the event template’s groupSize. Occurrences without an override inherit later series changes. An explicit occurrence limit takes precedence, even when smaller than the series limit. Availability, booking requests, confirmations, and waitlist operations use this capacity. Permissions, waiting-list settings, and coach overbooking rules apply.

Scopes

Event types

Event types label and categorize event templates for filtering and display.
Required scopes: event_types:read for reads, event_types:write for writes. Event type fields: Validation: Names and descriptions follow the localized text contract. Supported languages are nl, en, de, fr, and es. Unsupported language codes and the sourceLanguage input return 400. A language map replaces all translations for that field. Changing defaultLanguage requires that language in every retained nonempty text map.

Event templates

Event templates define the name, duration, default location, capacity, booking rules, visibility, pricing, credits, and optional eventType label for events.
Required scopes: event_templates:read for reads, event_templates:write for writes. List response fields: Event template fields: Validation:

List calendar events

Required scope: calendar_events:read Validation: Range limit: maximum 92 days. Response fields:

Get calendar event

Required scope: calendar_events:read Response fields:

Recurring bookings

Read recurring booking chains, update payment or end settings, manage pause windows, and cancel a chain.

List recurring bookings

Required scope: recurring_bookings:read Response fields:

Get recurring booking

Required scope: recurring_bookings:read Response fields:

Update recurring booking

Required scope: recurring_bookings:write Request body: Unknown fields are rejected with PUBLIC_API_UNKNOWN_FIELDS. Returns data.recurringBooking with the same fields as the detail response, plus:

Cancel recurring booking

Required scope: recurring_bookings:write Request body: Cancelling marks the chain as Cancelled and preserves its history and existing booking records. Returns data.recurringBooking with the same fields as the detail response, plus:

Calendar tasks

Required scope: calendar_tasks:read Response fields:

Get calendar task

Required scope: calendar_tasks:read Response fields:

Create calendar task

Required scope: calendar_tasks:write Request body: Unknown fields are rejected with PUBLIC_API_UNKNOWN_FIELDS. Returns data.task with the same fields as the detail response.

Update calendar task

Required scope: calendar_tasks:write Allowed fields: title, startAt, endAt, durationMinutes, notes, and assignedCoachIds. Unknown fields are rejected. Empty updates return NOTHING_TO_UPDATE. Returns data.task with the same fields as the detail response.

Cancel calendar task

Required scope: calendar_tasks:write Cancels the calendar task and returns its previous and new state. Response fields:

Booking requests

Required scope: booking_requests:read Response fields:

Approve booking request

Required scope: booking_requests:write Request body: The request must be pending, company-owned, and linked to a client visible to the authenticated Public API client. Response fields:

Reject booking request

Required scope: booking_requests:write Request body: Returns data.bookingRequest with the same fields as the approval response, plus:

Coach availability

Manage a coach’s working hours, date-specific availability, and days off. Use bookable availability to find slots that clients can book.
Required scope: coach_availability:read Response fields:

Replace coach availability

Required scope: coach_availability:write Request body: Unknown top-level fields are rejected. Send the coach ID in the path, not in the body.

Location availability

Manage a location’s weekly availability and date overrides. These rules are separate from its public opening hours. Use bookable availability to find slots that clients can book.
Required scope: location_availability:read Response fields:

Replace location availability

Required scope: location_availability:write Request body: Unknown top-level fields are rejected. Send the location ID in the path, not in the body.

Closure days and absence

Manage holiday presets and custom closure or absence dates that block availability for coaches, locations, or both.
Required scope: availability_rules:read Response fields:

Replace closure days and absence

Required scope: availability_rules:write Request body: Read the current closures, apply your changes, then send the complete desired presets and customClosures arrays. This endpoint replaces the configuration. Unknown top-level fields are rejected. The response returns data.availabilityClosures with the same fields as the read response.

List bookable availability

Required scope: availability:read Returns slots that are currently bookable or available for the waiting list, based on calendar events, coach and location availability, closures, capacity, booking rules, and optional client context. Each slot includes a signed, company-scoped availabilityToken that expires after 10 minutes. It does not reserve the slot. Creating a booking revalidates capacity and booking eligibility. Validation: Range limit: maximum 31 days. Response fields:

List bookings

Required scope: bookings:read Validation: Response fields:
Response:

Get booking

Required scope: bookings:read Response fields:

Create booking

Required scope: bookings:write Request body: Availability-token booking validation: Returns data.booking with the same fields as the detail response.
Response (201 Created):

Update booking attendance

Required scope: bookings:write Request body: Response fields:

Get booking cancellation context

Required scope: bookings:read Optional query: clientId, instanceDate. Response fields:

Cancel booking

Required scope: bookings:write Request body: Response fields:
Response:

Calendar query work budgets

Calendar occurrence lists apply cancellations and replacements before counting and paging. Normal pages return truncated=false. For very dense recurrence rules, large candidate/exception sets, or rules whose old start date requires too much scan work, the API returns 400 PUBLIC_API_CALENDAR_QUERY_TOO_COMPLEX. Use a smaller date range or more specific filters, then continue pagination. The error is explicit; the API never presents a partial occurrence set as complete.