calcom-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

最佳实践

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

创建预订前务必查询可用时段
存储预订UID以便后续操作（取消、重新安排）
谨慎处理时区转换 - 始终使用ISO 8601格式
实现Webhook处理程序以接收实时预订更新
缓存活动类型数据以减少API调用
对所有API调用使用适当的错误处理

calcom-api

Original

Translation

Cal.com API v2

Cal.com API v2

Base URL

基础URL

Authentication

身份验证

Core Concepts

核心概念

Event Types

活动类型

Bookings

预订

Schedules

日程表

Slots

可用时段

Common Operations

常见操作

Check Available Slots

查询可用时段

Create a Booking

创建预订

Get Bookings

查询预订列表

Get a Single Booking

查询单个预订

Cancel a Booking

取消预订

Reschedule a Booking

重新安排预订

List Event Types

列出活动类型

Get a Single Event Type

查询单个活动类型

Create an Event Type

创建活动类型

List Schedules

列出日程表

Get Default Schedule

查询默认日程表

Create a Schedule

创建日程表

Get Current User

查询当前用户

Team and Organization Endpoints

团队与组织端点

List Organization Teams

列出组织团队

Get Team Event Types

查询团队活动类型

Create Team Booking

创建团队预订

Webhooks

Webhook

List Webhooks

列出Webhook

Create a Webhook

创建Webhook

Calendar Integration

日历集成

List Connected Calendars

列出已连接的日历

Check Busy Times

查询忙碌时段

Error Handling

错误处理

Rate Limiting

速率限制

Pagination

分页

Best Practices

最佳实践

Additional Resources

其他资源