Skip to content
Docs

Group sessions

A group session is one scheduled occurrence of a group event type with a limited number of seats. Create sessions with an API key; invitees see them on the public schedule and book a seat without one. A seat is an ordinary booking with a sessionId.

Pass repeatWeeks when creating to repeat weekly (up to 26 occurrences). Cancelling with scope: "following" cancels this session and every later one in its series. Cancelling a session cancels each seat and notifies the attendees.

GET /public/:handle/schedule

Upcoming group sessions with seats left. Auth: none.

Path parameters

FieldTypeRequiredDefault / limits
handlestringyes-

Query parameters

FieldTypeRequiredDefault / limits
fromstring (date) | string (date-time)yes-
tostring (date) | string (date-time)yes-
tzstringnomin 1 chars
eventTypestringno1–600 chars

Response 200

Body

FieldTypeRequiredDefault / limits
hostobjectyes-
host.handlestringyes-
host.displayNamestringyes-
host.timezonestringyes-
eventTypesobject[]yes-
eventTypes[].slugstringyes-
eventTypes[].titlestringyes-
sessionsobject[]yes-
sessions[].idstring (uuid)yes-
sessions[].eventTypeSlugstringyes-
sessions[].titlestringyes-
sessions[].descriptionstringyes-
sessions[].startAtstring (date-time)yes-
sessions[].endAtstring (date-time)yes-
sessions[].capacityintegeryes-9007199254740991–9007199254740991
sessions[].seatsLeftintegeryes-9007199254740991–9007199254740991
sessions[].locationKind"url" | "phone" | "in_person" | "custom"yes-
sessions[].locationValuestringyes-
brandingbooleanyes-

Errors: invalid_request, not_found

curl -X GET "https://devalender.com/api/public/<handle>/schedule?from=2030-01-07&to=2030-01-07"

POST /public/:handle/:slug/sessions/:sessionId/bookings

Book a seat in a group session. Auth: none.

Path parameters

FieldTypeRequiredDefault / limits
handlestringyes-
slugstringyes-
sessionIdstringyes-

Request body

FieldTypeRequiredDefault / limits
inviteeNamestringyes1–100 chars
inviteeEmailstring (email)yes-
inviteeTimezonestringyesmin 1 chars

Response 201

Body

FieldTypeRequiredDefault / limits
bookingobjectyes-
booking.idstring (uuid)yes-
booking.eventTypeIdstring (uuid)yes-
booking.hostIdstring (uuid)yes-
booking.inviteeNamestringyes-
booking.inviteeEmailstring (email)yes-
booking.inviteeTimezonestringyes-
booking.startAtstring (date-time)yes-
booking.endAtstring (date-time)yes-
booking.status"confirmed" | "cancelled"yes-
booking.cancelReasonstring | nullyes-
booking.rescheduledFromIdstring (uuid) | nullyes-
booking.sessionIdstring (uuid)no-
booking.createdAtstring (date-time)yes-
manageTokenstringyes-
brandingbooleanyes-
demobooleanno-

Errors: invalid_request, not_found, session_full, already_booked, rate_limited

curl -X POST "https://devalender.com/api/public/<handle>/<slug>/sessions/<sessionId>/bookings" \
  -H "Content-Type: application/json" \
  -d '{"inviteeName":"string","inviteeEmail":"[email protected]","inviteeTimezone":"string"}'

GET /sessions

List sessions. Auth: API key.

Query parameters

FieldTypeRequiredDefault / limits
fromstring (date-time)no-
tostring (date-time)no-
eventTypeIdstring (uuid)no-

Response 200

Body (array of objects)

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
eventTypeIdstring (uuid)yes-
startAtstring (date-time)yes-
endAtstring (date-time)yes-
capacityintegeryes-9007199254740991–9007199254740991
seatsTakenintegeryes-9007199254740991–9007199254740991
status"scheduled" | "cancelled"yes-
seriesIdstring (uuid) | nullyes-

Errors: invalid_request, unauthorized

curl -X GET "https://devalender.com/api/sessions" \
  -H "Authorization: Bearer dvl_..."

POST /sessions

Create a session, optionally repeating weekly. Auth: API key.

Request body

FieldTypeRequiredDefault / limits
eventTypeIdstring (uuid)yes-
startAtstring (date-time)yes-
capacityintegerno1–500
repeatWeeksintegerno1–26

Response 201

Body (array of objects)

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
eventTypeIdstring (uuid)yes-
startAtstring (date-time)yes-
endAtstring (date-time)yes-
capacityintegeryes-9007199254740991–9007199254740991
seatsTakenintegeryes-9007199254740991–9007199254740991
status"scheduled" | "cancelled"yes-
seriesIdstring (uuid) | nullyes-

Errors: invalid_request, not_group_event_type, session_in_past, not_found, unauthorized

curl -X POST "https://devalender.com/api/sessions" \
  -H "Authorization: Bearer dvl_..." \
  -H "Content-Type: application/json" \
  -d '{"eventTypeId":"00000000-0000-4000-8000-000000000000","startAt":"2030-01-07T10:00:00Z"}'

PATCH /sessions/:id

Move a session or change its capacity. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Request body

FieldTypeRequiredDefault / limits
startAtstring (date-time)no-
capacityintegerno1–500

Response 200

Body

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
eventTypeIdstring (uuid)yes-
startAtstring (date-time)yes-
endAtstring (date-time)yes-
capacityintegeryes-9007199254740991–9007199254740991
seatsTakenintegeryes-9007199254740991–9007199254740991
status"scheduled" | "cancelled"yes-
seriesIdstring (uuid) | nullyes-

Errors: invalid_request, session_not_active, not_found, unauthorized

curl -X PATCH "https://devalender.com/api/sessions/<id>" \
  -H "Authorization: Bearer dvl_..." \
  -H "Content-Type: application/json" \
  -d '{"startAt":"2030-01-07T10:00:00Z"}'

POST /sessions/:id/cancel

Cancel one session or this and all following. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Request body

FieldTypeRequiredDefault / limits
scope"one" | "following"nodefault "one"
reasonstringnomax 500 chars

Response 200

Body (array of objects)

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
eventTypeIdstring (uuid)yes-
startAtstring (date-time)yes-
endAtstring (date-time)yes-
capacityintegeryes-9007199254740991–9007199254740991
seatsTakenintegeryes-9007199254740991–9007199254740991
status"scheduled" | "cancelled"yes-
seriesIdstring (uuid) | nullyes-

Errors: invalid_request, session_not_active, not_found, unauthorized

curl -X POST "https://devalender.com/api/sessions/<id>/cancel" \
  -H "Authorization: Bearer dvl_..." \
  -H "Content-Type: application/json" \
  -d '{"scope":"one"}'

GET /sessions/:id/attendees

Bookings holding a seat in a session. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Response 200

Body (array of objects)

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
eventTypeIdstring (uuid)yes-
hostIdstring (uuid)yes-
inviteeNamestringyes-
inviteeEmailstring (email)yes-
inviteeTimezonestringyes-
startAtstring (date-time)yes-
endAtstring (date-time)yes-
status"confirmed" | "cancelled"yes-
cancelReasonstring | nullyes-
rescheduledFromIdstring (uuid) | nullyes-
sessionIdstring (uuid)no-
createdAtstring (date-time)yes-

Errors: not_found, unauthorized

curl -X GET "https://devalender.com/api/sessions/<id>/attendees" \
  -H "Authorization: Bearer dvl_..."