Cal.com

01

Setup

1. 01Create a Cal.com API key. In Cal.com open Settings → Developer → API keys and create a key (cal_live_...). Set it to never expire: keys expire after 30 days by default, and an expired key stops every call until you paste a new one.
2. 02Paste it. In the superagnt app open Integrations, pick Cal.com and paste the key. If Connect with Cal.com is offered, click Use API key instead to reach the key field. On a self-hosted Cal.com, also fill in Self-hosted API URL.

A Cal.com key has no scopes: it acts with your full Cal.com permissions.

API key or OAuth

An API key covers every tool. The Cal.com OAuth connection (Connect with Cal.com, where it is offered) requests only BOOKING_READ, BOOKING_WRITE, EVENT_TYPE_READ and PROFILE_READ, so it covers bookings, slots, event-type reads and your profile. These need an API key, and each tool's description says so:

• user-level webhooks, and creating, changing or deleting event-type webhooks
• schedules and out-of-office
• creating, updating and deleting event types
• updating your profile
• teams and organizations

When a workspace has both, calls use the OAuth connection, except on a self-hosted connection.

Self-hosted Cal.com

If you run Cal.com yourself, enter your instance's API v2 base URL in Self-hosted API URL when you paste the key, and leave it blank for Cal.com cloud (https://api.cal.com/v2). On a self-host, API v2 is its own service, so this is the full base URL, path included, for example https://cal-api.yourcompany.com/v2.

• It must be a public https:// address on the default port, with no query or login details. Private, internal and loopback addresses are refused when you save and again before every call.
• superagnt_ checks the key with GET /me against that URL before it saves the connection.
• A connection with a self-hosted URL always uses its pasted key, never a Cal.com OAuth connection, which reaches only Cal.com cloud.
• To change the URL later, open the connection, enter the new URL (or tick Switch back to https://api.cal.com/v2) and paste the key again in the same save.
• The open-source edition (Cal.diy) has no teams, organizations or routing forms, so those tools answer 404 there.

02

Plans and limits

• Team tools need Cal.com's Teams plan and a team role. Organization tools need the Organizations plan and an org admin or owner. Use organizationId from getMe as orgId.
• Routing-form responses are readable only on the Organizations plan. On Teams, form submissions reach you only as FORM_SUBMITTED webhooks.

03

Things to know

• Booking tools take the booking uid, not its numeric id.
• listBookings and listOrganizationBookings page by cursor: send each response's pagination.nextCursor back as cursor until pagination.hasMore is false. limit is 1 to 100 (default 50).
• status on those two takes one value. Omit it to walk every status; for several, run one request per status and merge on the booking uid.
• A booking's updatedAt is null until it first changes, so an incremental pull pairs afterUpdatedAt with an afterCreatedAt pass.
• Most other lists (a team's members, bookings and schedules, the organization lists, webhooks and out-of-office) page with take and skip. take is at most 250 on most of them, and 1,000 for organization users.
• Attendees, hosts, no-show flags, cancellation and reschedule details (rescheduledFromUid, rescheduledToUid) and booking-form answers come inline on every booking.
• Rescheduling cancels the original booking and creates a new one with a new uid.
• Reassigning works only on round-robin bookings.
• Cal Video recording and transcript links expire after 1 hour, and Cal Video keeps recordings for 30 days.
• The connection does not cover Cal.com's deprecated Platform endpoints, API key refresh, credits, or edits to a booking's attendees, guests and location.

04

Permissions

These defaults decide whether a superagnt_ agent runs a call or waits for a person (Permissions). Reads run without asking. Creating and changing event types, schedules and out-of-office entries run by default. Creating or changing a webhook and updating your profile ask by default. Creating, cancelling, rescheduling, confirming, declining and reassigning bookings, marking no-shows, asking an attendee to reschedule, and every delete always ask a person first, because they email attendees or cannot be undone.

05

Examples

Check the connection

curl "https://api.superagnt.com/v1/connections/calcom/me" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

List upcoming bookings

curl "https://api.superagnt.com/v1/connections/calcom/bookings?status=upcoming&limit=25" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

Find open slots for an event type

curl "https://api.superagnt.com/v1/connections/calcom/slots?eventTypeId=12345&start=2026-11-02&end=2026-11-06&timeZone=America/Los_Angeles" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

Create a booking

curl -X POST "https://api.superagnt.com/v1/connections/calcom/bookings" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeId": 12345,
    "start": "2026-11-03T17:00:00Z",
    "attendee": {
      "name": "Jenny Rosen",
      "email": "jenny.rosen@example.com",
      "timeZone": "America/Los_Angeles"
    }
  }'

Register a webhook

curl -X POST "https://api.superagnt.com/v1/connections/calcom/webhooks" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberUrl": "https://api.superagnt.com/webhooks/ingest/<endpoint id>",
    "active": true,
    "triggers": ["BOOKING_CREATED", "BOOKING_RESCHEDULED", "BOOKING_CANCELLED"],
    "version": "2021-10-20"
  }'

06

API versions

Cal.com versions each endpoint through a cal-api-version header and quietly answers an older response shape for a wrong or missing value. superagnt_ sends the version each endpoint's reference page names, and 2026-02-25, the bookings default, everywhere else. A REST caller can send its own cal-api-version header to override it.

Event-type reads stay on 2024-06-14 while creates and updates use 2026-06-12. A bookingFields array sent on an update replaces the whole set, so read the event type first and send every question you want kept.

07

Receiving Cal.com webhooks

createWebhook sends the user's events, across every event type, to a URL, and createEventTypeWebhook does the same for one event type. Both need an API-key connection. Point one at a superagnt_ inbound webhook endpoint to trigger an agent. Pick from 28 triggers (BOOKING_CREATED, BOOKING_RESCHEDULED, BOOKING_CANCELLED, BOOKING_NO_SHOW_UPDATED, MEETING_ENDED, RECORDING_READY, FORM_SUBMITTED, OOO_CREATED and more), and:

• Cal.com signs each delivery with X-Cal-Signature-256, a hex HMAC-SHA256 of the body under the webhook's secret, with no timestamp. An inbound endpoint does not check that header, so leave the endpoint's signature verification off and keep its URL secret. A receiver of your own should set secret, check the header and deduplicate deliveries.
• Send version: "2021-10-20" and never set payloadTemplate, so every delivery has the standard shape.
• The Cal Video no-show triggers (AFTER_HOSTS_CAL_VIDEO_NO_SHOW, AFTER_GUESTS_CAL_VIDEO_NO_SHOW) also need time and timeUnit.
• Cal.com cloud delivers only to public https:// URLs.
• Cal.com documents no delivery retries. Treat webhooks as best effort and reconcile with listBookings (afterUpdatedAt).

08

Sync

A Cal.com sync copies your bookings, their attendees, your event types and availability schedules (and, when you turn them on, your teams and every webhook delivery) into tables in your workspace database and keeps them fresh, so agents read local tables instead of calling Cal.com on every run. Turn it on from the Sync panel on the Cal.com connection page in the superagnt app. The panel previews the rows and webhook events against your plan before anything is created. How syncs work in general: Vendor sync.

How updates arrive. On an API-key connection the sync registers one Cal.com webhook of its own for booking changes (created, rescheduled, cancelled, requested, rejected, no-show, reassigned, location changed and paid), with a secret only the sync holds, and checks the signature on every delivery. A delivery makes the sync re-read that booking from the API, so the tables always hold the API's shape. Polling picks up bookings created or updated since the last pass, and once a day re-reads the last week of bookings, because a cancellation or no-show may not change a booking's updatedAt. Triggers with no booking behind them (meetings started and ended, form submissions, recordings and more) are opt-in and land only in calcom_events.

Plans and scope.

• A connection made with OAuth syncs by polling only and cannot sync schedules or teams, because its grant covers bookings, event types and the profile. Connect with an API key for webhooks.
• Event types are a filter on the sync: pick the ones whose bookings it copies.
• The sync's calls share Cal.com's per-key rate limit with your agents' Cal.com tool calls, so it keeps well under it.

What a Cal.com sync copies

A sync copies these tables into your workspace database and keeps them fresh, so an agent reads local rows instead of calling Cal.com on every run. Turn tables on and off from the Sync panel on the connection. Every table also carries _raw, _hash, _synced_at and _deleted_at. How syncs work: Vendor sync.

21 tools, one per resource and risk

MCP servers and agents on the grouped surface list Cal.com as these tools. Each takes an action, and the ones that work across record types an object. Every operation also keeps its own per-operation name, in the next table, which works on every server. How grouping works: Grouped tools.

All 55 operations

Each operation is a REST path under https://api.superagnt.com/v1/connections/calcom and an MCP tool. The per-operation tool name is the one permissions, approvals and usage records use.

Related