Back to Details

calcom-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cal.com API v2

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.
本技能为AI Agent提供与Cal.com API v2交互的指导，可实现日程自动化、预订管理和日历集成功能。

Base URL

基础URL

All API requests should be made to:
https://api.cal.com/v2
所有API请求都应发送至：
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.
所有API请求都需要通过Authorization头中的Bearer token进行身份验证：
Authorization: Bearer cal_<your_api_key>
API密钥必须以
cal_
为前缀。你可以在Cal.com仪表板的「设置 > 开发者 > API密钥」页面生成API密钥。

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.
活动类型定义了可预订会议的配置（时长、地点、可用时间规则）。每个活动类型都有一个唯一的slug，用于预订URL中。

Bookings

预订

Bookings are confirmed appointments created when someone books an event type. Each booking has a unique UID for identification.
预订是当用户预订某个活动类型时创建的已确认预约。每个预订都有一个唯一的UID用于标识。

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:
http
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 range
  • endTime
    (required): ISO 8601 end of range
  • eventTypeId
    or 
    eventTypeSlug
    : Identify the event type
  • timeZone
    : Timezone for slot display (default: UTC)
Response contains available slots grouped by date.
创建预订前，请先查询可用时段：
http
GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=123&eventTypeSlug=30min
查询参数：
  • startTime
    （必填）：ISO 8601格式的时间范围起始值
  • endTime
    （必填）：ISO 8601格式的时间范围结束值
  • eventTypeId
    或 
    eventTypeSlug
    ：用于指定活动类型
  • timeZone
    ：可用时段显示的时区（默认：UTC）
响应结果会按日期分组返回可用时段。

Create a Booking

创建预订

http
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 time
  • eventTypeId
    : ID of the event type to book
  • attendee.name
    : Attendee's full name
  • attendee.email
    : Attendee's email address
  • attendee.timeZone
    : Attendee's timezone
http
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": {}
}
必填字段：
  • start
    ：ISO 8601格式的预订开始时间
  • eventTypeId
    ：要预订的活动类型ID
  • attendee.name
    ：参会人的全名
  • attendee.email
    ：参会人的邮箱地址
  • attendee.timeZone
    ：参会人的时区

Get Bookings

查询预订列表

List bookings with optional filters:
http
GET /v2/bookings?status=upcoming&take=10
Query parameters:
  • status
    : Filter by status (upcoming, recurring, past, cancelled, unconfirmed)
  • attendeeEmail
    : Filter by attendee email
  • eventTypeId
    : Filter by event type
  • take
    : Number of results (max 250)
  • skip
    : Pagination offset
通过可选筛选条件列出预订：
http
GET /v2/bookings?status=upcoming&take=10
查询参数：
  • status
    ：按状态筛选（upcoming：即将到来，recurring：周期性，past：已结束，cancelled：已取消，unconfirmed：未确认）
  • attendeeEmail
    ：按参会人邮箱筛选
  • eventTypeId
    ：按活动类型筛选
  • take
    ：返回结果数量（最大250）
  • skip
    ：分页偏移量

Get a Single Booking

查询单个预订

http
GET /v2/bookings/{bookingUid}
http
GET /v2/bookings/{bookingUid}

Cancel a Booking

取消预订

http
POST /v2/bookings/{bookingUid}/cancel
Content-Type: application/json

{
  "cancellationReason": "Schedule conflict"
}
http
POST /v2/bookings/{bookingUid}/cancel
Content-Type: application/json

{
  "cancellationReason": "Schedule conflict"
}

Reschedule a Booking

重新安排预订

http
POST /v2/bookings/{bookingUid}/reschedule
Content-Type: application/json

{
  "start": "2024-01-16T14:00:00Z",
  "reschedulingReason": "Conflict with another meeting"
}
http
POST /v2/bookings/{bookingUid}/reschedule
Content-Type: application/json

{
  "start": "2024-01-16T14:00:00Z",
  "reschedulingReason": "Conflict with another meeting"
}

List Event Types

列出活动类型

http
GET /v2/event-types
Returns all event types for the authenticated user.
http
GET /v2/event-types
返回已认证用户的所有活动类型。

Get a Single Event Type

查询单个活动类型

http
GET /v2/event-types/{eventTypeId}
http
GET /v2/event-types/{eventTypeId}

Create an Event Type

创建活动类型

http
POST /v2/event-types
Content-Type: application/json

{
  "title": "30 Minute Meeting",
  "slug": "30min",
  "lengthInMinutes": 30,
  "locations": [
    {
      "type": "integration",
      "integration": "cal-video"
    }
  ]
}
http
POST /v2/event-types
Content-Type: application/json

{
  "title": "30 Minute Meeting",
  "slug": "30min",
  "lengthInMinutes": 30,
  "locations": [
    {
      "type": "integration",
      "integration": "cal-video"
    }
  ]
}

List Schedules

列出日程表

http
GET /v2/schedules
http
GET /v2/schedules

Get Default Schedule

查询默认日程表

http
GET /v2/schedules/default
http
GET /v2/schedules/default

Create a Schedule

创建日程表

http
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.).
http
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"
    }
  ]
}
日期为0索引（0=周日，1=周一，以此类推）。

Get Current User

查询当前用户

http
GET /v2/me
Returns the authenticated user's profile information.
http
GET /v2/me
返回已认证用户的个人资料信息。

Team and Organization Endpoints

团队与组织端点

For team bookings and organization management, use the organization-scoped endpoints:
如需进行团队预订和组织管理，请使用组织范围的端点：

List Organization Teams

列出组织团队

http
GET /v2/organizations/{orgId}/teams
http
GET /v2/organizations/{orgId}/teams

Get Team Event Types

查询团队活动类型

http
GET /v2/organizations/{orgId}/teams/{teamId}/event-types
http
GET /v2/organizations/{orgId}/teams/{teamId}/event-types

Create Team Booking

创建团队预订

Team event types support different scheduling modes:
  • COLLECTIVE
    : All team members must attend
  • ROUND_ROBIN
    : Distributes bookings among team members
团队活动类型支持不同的调度模式：
  • COLLECTIVE
    ：所有团队成员必须参会
  • ROUND_ROBIN
    ：在团队成员之间分配预订

Webhooks

Webhook

Configure webhooks to receive real-time notifications:
配置Webhook以接收实时通知：

List Webhooks

列出Webhook

http
GET /v2/webhooks
http
GET /v2/webhooks

Create a Webhook

创建Webhook

http
POST /v2/webhooks
Content-Type: application/json

{
  "subscriberUrl": "https://your-app.com/webhook",
  "triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"],
  "active": true
}
Available triggers:
  • BOOKING_CREATED
  • BOOKING_CANCELLED
  • BOOKING_RESCHEDULED
  • BOOKING_CONFIRMED
  • MEETING_STARTED
  • MEETING_ENDED
http
POST /v2/webhooks
Content-Type: application/json

{
  "subscriberUrl": "https://your-app.com/webhook",
  "triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"],
  "active": true
}
可用触发事件：
  • BOOKING_CREATED
    ：预订已创建
  • BOOKING_CANCELLED
    ：预订已取消
  • BOOKING_RESCHEDULED
    ：预订已重新安排
  • BOOKING_CONFIRMED
    ：预订已确认
  • MEETING_STARTED
    ：会议已开始
  • MEETING_ENDED
    ：会议已结束

Calendar Integration

日历集成

List Connected Calendars

列出已连接的日历

http
GET /v2/calendars
http
GET /v2/calendars

Check Busy Times

查询忙碌时段

http
GET /v2/calendars/busy-times?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z
http
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
    : Success
  • 201
    : Created
  • 400
    : Bad Request (invalid parameters)
  • 401
    : Unauthorized (invalid or missing API key)
  • 403
    : Forbidden (insufficient permissions)
  • 404
    : Not Found
  • 422
    : Unprocessable Entity (validation error)
  • 500
    : Internal Server Error
Error responses include a message field:
json
{
  "status": "error",
  "message": "Booking not found"
}
API返回标准HTTP状态码：
  • 200
    ：成功
  • 201
    ：已创建
  • 400
    ：错误请求（参数无效）
  • 401
    ：未授权（API密钥无效或缺失）
  • 403
    ：禁止访问（权限不足）
  • 404
    ：未找到
  • 422
    ：无法处理的实体（验证错误）
  • 500
    ：内部服务器错误
错误响应包含message字段：
json
{
  "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.
API实施速率限制。如果超出限制，你将收到
429 Too Many Requests
响应。请实现指数退避策略进行重试。

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
列表端点通过
take
和
skip
参数支持分页：
  • take
    ：返回的项目数量（默认：10，最大：250）
  • skip
    ：跳过的项目数量

Best Practices

最佳实践

  1. Always check slot availability before creating bookings
  2. Store booking UIDs for future reference (cancel, reschedule)
  3. Handle timezone conversions carefully - always use ISO 8601 format
  4. Implement webhook handlers for real-time booking updates
  5. Cache event type data to reduce API calls
  6. Use appropriate error handling for all API calls
  1. 创建预订前务必查询可用时段
  2. 存储预订UID以便后续操作（取消、重新安排）
  3. 谨慎处理时区转换 - 始终使用ISO 8601格式
  4. 实现Webhook处理程序以接收实时预订更新
  5. 缓存活动类型数据以减少API调用
  6. 对所有API调用使用适当的错误处理

Additional Resources

其他资源