OpenAPI Marketplace

Cal.com Scheduling

Name: Cal.com Scheduling
Author: vx.ai

v1.0.0 · 10 endpoints · 0 connections · shared by vx.ai

Let an agent book, reschedule and cancel meetings and appointments in Cal.com: list event types, find open slots, create bookings and track no-shows. Works with Cal.com cloud and self-hosted instances. Curated from Cal.com's official API v2 OpenAPI specification.

Connect this API to an AI agent Browse all specs

What you can do with Cal.com Scheduling via MCP

Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.

Method	Path	Operation	Description
GET	`/v2/me`	getMe	Get the connected Cal.com user
GET	`/v2/event-types`	listEventTypes	List event types (bookable services)
GET	`/v2/event-types/{eventTypeId}`	getEventType	Get one event type
GET	`/v2/slots`	getAvailableSlots	Find available time slots
GET	`/v2/bookings`	listBookings	List bookings
POST	`/v2/bookings`	createBooking	Book a time slot
GET	`/v2/bookings/{bookingUid}`	getBooking	Get one booking
POST	`/v2/bookings/{bookingUid}/reschedule`	rescheduleBooking	Reschedule a booking
POST	`/v2/bookings/{bookingUid}/cancel`	cancelBooking	Cancel a booking
POST	`/v2/bookings/{bookingUid}/mark-absent`	markNoShow	Mark the host or attendees as no-show

Authentication

calApiKey

Bearer token — sent as Authorization: Bearer <token>

Cal.com API key, sent as Authorization: Bearer cal_live_….

How to get a key

In Cal.com open Settings → Developer → API keys (cloud: app.cal.com/settings/developer/api-keys).
Create a key, choose an expiry, and copy it once (cal_live_…; test keys start with cal_test_).
Store it as a credential in VX Agents so the model never sees it.
Self-hosted Cal.com: use a copy of this spec whose base URL is your instance's API URL.

The key acts as the user who created it: the agent sees that user's event types and bookings.

Required version headers

Each endpoint group pins its cal-api-version header (already set in this spec): bookings 2024-08-13, slots 2024-09-04, event types 2024-06-14.

Common errors

401 – missing, wrong or expired key.
400 with a version message – the cal-api-version header was changed; keep the pinned value.
404 on a booking – use the booking uid, not the numeric id.

Usage guide

Setup

Connect this spec to an agent and add your Cal.com API key as the credential (see Authentication).
Call listEventTypes once. Pin the eventTypeId of the service the agent should book (for example a 30-minute consultation) as a preset parameter.

Booking flow

getAvailableSlots with the event type, a start/end range and the customer's timeZone.
Offer two or three slots to the customer in their time zone.
createBooking with start (UTC ISO 8601), eventTypeId and attendee (name, email, timeZone, optional phoneNumber, language).
Read back the confirmed time and the booking uid.

Reschedule with rescheduleBooking (new start), cancel with cancelBooking (add a cancellationReason). Confirm both with the customer first.

Follow-up

listBookings filtered by status (upcoming, past, cancelled) or attendee email to answer "when is my appointment?".
markNoShow after a missed appointment, so reports and follow-ups are accurate.

Good to know

Bookings use the booking uid (a string), never the numeric id.
Event types that require confirmation create bookings in pending until the host accepts.
cal-api-version headers are pinned per endpoint in this spec; do not change them.

How to use this spec

Create a free VX Agents account (sandbox tools included).
Open the marketplace and connect “Cal.com Scheduling” to an agent.
Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.