Skip to main content

Bookings

The Bookings API gives integrations read access to your workspace's bookings and booking types (event types). It pairs with outbound webhooks that notify your systems whenever a booking changes — created, confirmed, cancelled, rescheduled, declined, reassigned, or flagged as a no-show.

The read endpoints are scoped to your token's workspace: you can never read another workspace's bookings.

Quick Start​

# List bookings (newest first, keyset pagination)
curl -X GET "https://api.copera.ai/public/v1/bookings?status=CONFIRMED&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a single booking by its public uid
curl -X GET https://api.copera.ai/public/v1/bookings/BOOKING_UID \
  -H "Authorization: Bearer YOUR_API_KEY"

# List booking types (event types)
curl -X GET https://api.copera.ai/public/v1/booking-types \
  -H "Authorization: Bearer YOUR_API_KEY"

Available in​

Public APICLIMCPCopera AI
✅ Read-only———

The read endpoints are available over the Public API. Bookings are not yet exposed through the CLI, the hosted MCP server, or the in-app Copera AI assistant.

info

The Bookings endpoints are not yet in the live API Reference — production hasn't shipped the OpenAPI surface for them. Until then, this guide is the reference; use the request shapes below with the Public API.

Read-only surface​

The Public API exposes three GET endpoints. There are no create, cancel, confirm, decline, or reschedule endpoints — bookings are managed inside the Copera app and read through the API.

List bookings​

GET /public/v1/bookings returns the workspace's bookings, newest first, with keyset pagination. Query parameters (all optional):

  • status — PENDING, CONFIRMED, DECLINED, CANCELLED, or COMPLETED.
  • bookingTypeId — restrict to a single booking type.
  • from / to — ISO-8601 date-times; filter by the booking's start time.
  • limit — 1–100 (default 25).
  • cursor — the nextCursor from a previous response.
curl -X GET "https://api.copera.ai/public/v1/bookings?status=CONFIRMED&limit=25" \
  -H "Authorization: Bearer YOUR_TOKEN"

The response is keyset-paginated:

{ "bookings": [ /* … */ ], "nextCursor": "…", "hasMore": true }

Get a booking​

GET /public/v1/bookings/{uid} returns a single booking by its public uid.

List booking types​

GET /public/v1/booking-types returns the workspace's booking types (event types). It takes no parameters and returns all of them, including hidden and inactive ones (each carries hidden and active flags so you can filter client-side).

What a booking contains​

A booking object includes its uid, status, the bookingTypeId and bookingTypeTitle, start / end / durationMinutes, timezoneAtBooking, the hosts (each { userId, role }), the booker (name, email, optional phone, timezone, locale), guests, the form answers, and the location. Because this is your own workspace's data, booker contact details are included; internal handles such as the manage token and idempotency key are never exposed.

A booking type includes its _id, title, optional slug and description, kind, durationMinutes, optional color, the hidden and active flags, and timestamps.

Webhooks​

Beyond reading bookings, you can receive outbound webhooks that notify your systems whenever a booking changes. See Booking Webhooks for the event list, the signed payload, the headers, signature verification, and the delivery/retry contract.

Authentication & scope​

Bookings endpoints accept a full Personal Access Token (cp_pat_) or an integration API key (cp_key_) with the access_bookings scope. A token missing the scope gets a 403. See Authentication.

Reference​

  • Booking Webhooks — the event list, signed payload, headers, signature verification, and delivery/retry contract.
  • Authentication and Pagination — token scopes and the keyset cursor model used by list bookings.