calcom-api
Interact with the Cal.com API v2 to manage scheduling, bookings, event types, availability, and calendars. Use this skill when building integrations that need to create or manage bookings, check availability, configure event types, or sync calendars with Cal.com's scheduling infrastructure.
- License 许可
- MIT
- 最近更新
- 2026-06-07
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- calcom-api
- license
- MIT
- metadata
- { "author": "calcom", "version": "1.0.0", "api-version": "v2" }
- description
- Interact with the Cal.com API v2 to manage scheduling, bookings, event types, availability, and calendars. Use this skill when building integrations that need to create or manage bookings, check availability, configure event types, or sync calendars with Cal.com's scheduling infrastructure.
03 SKILL.md 正文
Cal.com API v2
This skill provides guidance for AI agents to interact with the Cal.com API v2, enabling scheduling automation, booking management, and calendar integrations.
Base URL
All API requests should be made to:
https://api.cal.com/v2
Authentication
All API requests require authentication via Bearer token in the Authorization header:
Authorization: Bearer cal_<your_api_key>
API keys must be prefixed with cal_. You can generate API keys from your Cal.com dashboard under Settings > Developer > API Keys.
Core Concepts
Event Types
Event types define bookable meeting configurations (duration, location, availability rules). Each event type has a unique slug used in booking URLs.
Bookings
Bookings are confirmed appointments created when someone books an event type. Each booking has a unique UID for identification.
Schedules
Schedules define when a user is available for bookings. Users can have multiple schedules with different working hours.
Slots
Slots represent available time windows that can be booked based on event type configuration and user availability.
Common Operations
Check Available Slots
Before creating a booking, check available time slots:
GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=123&eventTypeSlug=30min
Query parameters:
startTime(required): ISO 8601 start of rangeendTime(required): ISO 8601 end of rangeeventTypeIdoreventTypeSlug: Identify the event typetimeZone: Timezone for slot display (default: UTC)
Response contains available slots grouped by date.
Create a Booking
POST /v2/bookings
Content-Type: application/json
{
"start": "2024-01-15T10:00:00Z",
"eventTypeId": 123,
"attendee": {
"name": "John Doe",
"email": "john@example.com",
"timeZone": "America/New_York"
},
"meetingUrl": "https://cal.com/team/meeting",
"metadata": {}
}
Required fields:
start: ISO 8601 booking start timeeventTypeId: ID of the event type to bookattendee.name: Attendee's full nameattendee.email: Attendee's email addressattendee.timeZone: Attendee's timezone
Get Bookings
List bookings with optional filters:
GET /v2/bookings?status=upcoming&take=10
Query parameters:
status: Filter by status (upcoming, recurring, past, cancelled, unconfirmed)attendeeEmail: Filter by attendee emaileventTypeId: Filter by event typetake: Number of results (max 250)skip: Pagination offset
Get a Single Booking
GET /v2/bookings/{bookingUid}
Cancel a Booking
POST /v2/bookings/{bookingUid}/cancel
Content-Type: application/json
{
"cancellationReason": "Schedule conflict"
}
Reschedule a Booking
POST /v2/bookings/{bookingUid}/reschedule
Content-Type: application/json
{
"start": "2024-01-16T14:00:00Z",
"reschedulingReason": "Conflict with another meeting"
}
List Event Types
GET /v2/event-types
Returns all event types for the authenticated user.
Get a Single Event Type
GET /v2/event-types/{eventTypeId}
Create an Event Type
POST /v2/event-types
Content-Type: application/json
{
"title": "30 Minute Meeting",
"slug": "30min",
"lengthInMinutes": 30,
"locations": [
{
"type": "integration",
"integration": "cal-video"
}
]
}
List Schedules
GET /v2/schedules
Get Default Schedule
GET /v2/schedules/default
Create a Schedule
POST /v2/schedules
Content-Type: application/json
{
"name": "Working Hours",
"timeZone": "America/New_York",
"isDefault": true,
"availability": [
{
"days": [1, 2, 3, 4, 5],
"startTime": "09:00",
"endTime": "17:00"
}
]
}
Days are 0-indexed (0 = Sunday, 1 = Monday, etc.).
Get Current User
GET /v2/me
Returns the authenticated user's profile information.
Team and Organization Endpoints
For team bookings and organization management, use the organization-scoped endpoints:
List Organization Teams
GET /v2/organizations/{orgId}/teams
Get Team Event Types
GET /v2/organizations/{orgId}/teams/{teamId}/event-types
Create Team Booking
Team event types support different scheduling modes:
COLLECTIVE: All team members must attendROUND_ROBIN: Distributes bookings among team members
Webhooks
Configure webhooks to receive real-time notifications:
List Webhooks
GET /v2/webhooks
Create a Webhook
POST /v2/webhooks
Content-Type: application/json
{
"subscriberUrl": "https://your-app.com/webhook",
"triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"],
"active": true
}
Available triggers:
BOOKING_CREATEDBOOKING_CANCELLEDBOOKING_RESCHEDULEDBOOKING_CONFIRMEDMEETING_STARTEDMEETING_ENDED
Calendar Integration
List Connected Calendars
GET /v2/calendars
Check Busy Times
GET /v2/calendars/busy-times?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z
Error Handling
The API returns standard HTTP status codes:
200: Success201: Created400: Bad Request (invalid parameters)401: Unauthorized (invalid or missing API key)403: Forbidden (insufficient permissions)404: Not Found422: Unprocessable Entity (validation error)500: Internal Server Error
Error responses include a message field:
{
"status": "error",
"message": "Booking not found"
}
Rate Limiting
The API implements rate limiting. If you exceed the limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff for retries.
Pagination
List endpoints support pagination via take and skip parameters:
take: Number of items to return (default: 10, max: 250)skip: Number of items to skip
Best Practices
- Always check slot availability before creating bookings
- Store booking UIDs for future reference (cancel, reschedule)
- Handle timezone conversions carefully - always use ISO 8601 format
- Implement webhook handlers for real-time booking updates
- Cache event type data to reduce API calls
- Use appropriate error handling for all API calls
Additional Resources
04 同仓库更多 Skills
crowd-prompting
A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.
ceaser
Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).
ceaser-send
Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.
dilemm-ai
Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).
moldium
Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.
arxiv-paper-reviews
Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.