GET POST
bookings/
User API Service tier
List bookings, or create one with POST. derived from route
URL
User API https://calendar.mattering.io/api/user/v1/bookings/
Service tier https://calendar.mattering.io/api/internal/v1/bookings/
Pagination
Accepts limit and offset. The response meta carries total, limit and offset.
Responses
200 data and meta envelope
{
"data": [
"..."
],
"meta": {
"total": 0,
"limit": 0,
"offset": 0,
"returned": 0,
"has_more": true
}
}
201 data and meta envelope
{
"data": {
"id": "...",
"public_id": "...",
"kind": "...",
"title": "...",
"description": "...",
"event_type_id": "...",
"event_type_name": "...",
"host_email": "...",
"invitee_name": "...",
"invitee_email": "...",
"invitee_timezone": "...",
"timezone": "...",
"attendees": [
{
"name": "...",
"email": "...",
"is_internal": true
}
],
"notes": [
"..."
],
"location": "...",
"meeting_url": "...",
"is_all_day": true,
"color": "...",
"start_at": "2026-01-01T00:00:00Z",
"end_at": "2026-01-01T00:00:00Z",
"duration_minutes": "...",
"status": "...",
"canceled_by": "...",
"cancel_reason": "...",
"source": "...",
"space_id": "...",
"external_links": "...",
"created_at": "2026-01-01T00:00:00Z",
"manage_url": "..."
},
"meta": {
"ignored_fields": [
"..."
]
}
}
201 data and meta envelope
{
"data": {
"id": "...",
"public_id": "...",
"kind": "...",
"title": "...",
"description": "...",
"event_type_id": "...",
"event_type_name": "...",
"host_email": "...",
"invitee_name": "...",
"invitee_email": "...",
"invitee_timezone": "...",
"timezone": "...",
"attendees": [
{
"name": "...",
"email": "...",
"is_internal": true
}
],
"notes": [
"..."
],
"location": "...",
"meeting_url": "...",
"is_all_day": true,
"color": "...",
"start_at": "2026-01-01T00:00:00Z",
"end_at": "2026-01-01T00:00:00Z",
"duration_minutes": "...",
"status": "...",
"canceled_by": "...",
"cancel_reason": "...",
"source": "...",
"space_id": "...",
"external_links": "...",
"created_at": "2026-01-01T00:00:00Z",
"manage_url": "..."
},
"meta": {
"ignored_fields": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 bad_request401 unauthorized404 not_found405 method_not_allowed409 conflict410 inactive
Example
User API Service tier
curl -X GET "https://calendar.mattering.io/api/user/v1/bookings/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X GET "https://calendar.mattering.io/api/internal/v1/bookings/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: CalendarCore/internal_api.py (internal_api.bookings)
POST
bookings/{public_id} /cancel/
User API Service tier
POST to bookings/{public_id}/cancel/. derived from route
URL
User API https://calendar.mattering.io/api/user/v1/bookings/{public_id} /cancel/
Service tier https://calendar.mattering.io/api/internal/v1/bookings/{public_id} /cancel/
Path parameters
Body keys (JSON)
Key Required Default
reasonoptional or conditional none
Keys the view reads. A key not in this list is ignored by the view. Where a key is required only for some actions (for example the action dispatch), the description above says which.
Responses
200 data and meta envelope
{
"data": {
"id": "...",
"public_id": "...",
"kind": "...",
"title": "...",
"description": "...",
"event_type_id": "...",
"event_type_name": "...",
"host_email": "...",
"invitee_name": "...",
"invitee_email": "...",
"invitee_timezone": "...",
"timezone": "...",
"attendees": [
{
"name": "...",
"email": "...",
"is_internal": true
}
],
"notes": [
"..."
],
"location": "...",
"meeting_url": "...",
"is_all_day": true,
"color": "...",
"start_at": "2026-01-01T00:00:00Z",
"end_at": "2026-01-01T00:00:00Z",
"duration_minutes": "...",
"status": "...",
"canceled_by": "...",
"cancel_reason": "...",
"source": "...",
"space_id": "...",
"external_links": "...",
"created_at": "2026-01-01T00:00:00Z",
"manage_url": "..."
},
"meta": {
"canceled": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
401 unauthorized404 not_found
Example
User API Service tier
curl -X POST "https://calendar.mattering.io/api/user/v1/bookings/PUBLIC_ID/cancel/" \
-H "Authorization: Bearer $MATTERING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "..."
}' curl -X POST "https://calendar.mattering.io/api/internal/v1/bookings/PUBLIC_ID/cancel/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com" \
-H "Content-Type: application/json" \
-d '{
"reason": "..."
}'
Source: CalendarCore/internal_api.py (internal_api.booking_cancel)
POST
bookings/{public_id} /update/
User API Service tier
Update a meeting in place.
Scheduled meetings are freely editable (they answer to no published availability). For BOOKED meetings only the non-scheduling fields are accepted: moving one has to go through the availability engine, so a reschedule is a cancel plus a new booking rather than a silent edit that could land on an unavailable slot.
Body: any of title, description, location, meeting_url, notes, invitee_name, invitee_email, invitee_timezone (alias timezone), is_all_day, external_links, host_email, status (+ cancel_reason), start_at (alias start_time), end_at (alias end_time), attendees. meta.updated names what changed and meta.ignored_fields what was not understood. A body that changes nothing is a 400 no_writable_fields rather than a 200 that did nothing.
URL
User API https://calendar.mattering.io/api/user/v1/bookings/{public_id} /update/
Service tier https://calendar.mattering.io/api/internal/v1/bookings/{public_id} /update/
Path parameters
Responses
200 data and meta envelope
{
"data": {
"id": "...",
"public_id": "...",
"kind": "...",
"title": "...",
"description": "...",
"event_type_id": "...",
"event_type_name": "...",
"host_email": "...",
"invitee_name": "...",
"invitee_email": "...",
"invitee_timezone": "...",
"timezone": "...",
"attendees": [
{
"name": "...",
"email": "...",
"is_internal": true
}
],
"notes": [
"..."
],
"location": "...",
"meeting_url": "...",
"is_all_day": true,
"color": "...",
"start_at": "2026-01-01T00:00:00Z",
"end_at": "2026-01-01T00:00:00Z",
"duration_minutes": "...",
"status": "...",
"canceled_by": "...",
"cancel_reason": "...",
"source": "...",
"space_id": "...",
"external_links": "...",
"created_at": "2026-01-01T00:00:00Z",
"manage_url": "..."
},
"meta": {
"updated": "...",
"ignored_fields": "..."
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
Status Code
400 bad_request400 no_writable_fields401 unauthorized404 not_found409 unsupported
Example
User API Service tier
curl -X POST "https://calendar.mattering.io/api/user/v1/bookings/PUBLIC_ID/update/" \
-H "Authorization: Bearer $MATTERING_API_KEY" curl -X POST "https://calendar.mattering.io/api/internal/v1/bookings/PUBLIC_ID/update/" \
-H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \
-H "X-Internal-Org-Id: $ORG_ID" \
-H "X-Internal-User-Email: you@example.com"
Source: CalendarCore/internal_api.py (internal_api.booking_update)