calcom-api

Cal.diy API v2

このスキルは、AI エージェントが Cal.diy API v2 と連携するためのガイダンスを提供し、スケジューリングの自動化、予約管理、カレンダー連携を可能にします。

ベース URL

すべての API リクエストは以下に対して行う必要があります:

https://api.cal.com/v2

必要な認証情報

環境変数	必須	説明
CAL_API_KEY	はい	Cal.diy API キー（cal_live_ または cal_test_ というプレフィックスが付きます）。すべての API リクエストの Bearer トークンとして使用されます。Settings > Developer > API Keys から生成してください。
CAL_CLIENT_ID	いいえ	他のユーザーに代わってユーザーを管理するプラットフォーム連携用の OAuth クライアント ID。x-cal-client-id ヘッダーとして送信されます。
CAL_SECRET_KEY	いいえ	プラットフォーム連携用の OAuth クライアントシークレット。x-cal-secret-key ヘッダーとして送信されます。
CAL_WEBHOOK_SECRET	いいえ	X-Cal-Signature-256 ヘッダーを介して Webhook ペイロードの署名を検証するためのシークレット。

認証

すべての API リクエストは Bearer トークンによる認証が必要です:

Authorization: Bearer cal_<your_api_key>

OAuth／プラットフォーム認証を含む詳細な認証方法については、references/authentication.md を参照してください。

基本概念

イベントタイプは、予約可能な会議の構成（所要時間、場所、空き時間ルール）を定義します。各イベントタイプには、予約 URL で使用される一意のスラッグがあります。

予約は、誰かがイベントタイプを予約したときに作成される確定済みのアポイントメントです。各予約には識別用の一意の UID があります。

スケジュールは、ユーザーが予約に対応可能な時間を定義します。ユーザーは異なる勤務時間を持つ複数のスケジュールを持つことができます。

スロットは、イベントタイプの構成とユーザーの空き状況に基づいて予約可能な、利用可能な時間枠を表します。

リファレンスドキュメント

このスキルには、各ドメインの詳細な API リファレンスドキュメントが含まれています:

リファレンス	説明
references/authentication.md	API キーと OAuth 認証、レート制限、セキュリティのベストプラクティス
references/bookings.md	予約の作成、一覧表示、キャンセル、再スケジュール
references/event-types.md	予約可能な会議タイプの構成
references/schedules.md	ユーザーの空き時間スケジュールの管理
references/slots-availability.md	利用可能な時間枠の照会
references/calendars.md	カレンダー接続と予定あり時間
references/webhooks.md	リアルタイムのイベント通知

クイックスタート

1. 利用可能なスロットを確認する

予約を作成する前に、利用可能な時間枠を確認します:

GET /v2/slots?startTime=2024-01-15T00:00:00Z&endTime=2024-01-22T00:00:00Z&eventTypeId=123

詳細については、references/slots-availability.md を参照してください。

2. 予約を作成する

POST /v2/bookings
Content-Type: application/json

{
  "start": "2024-01-15T10:00:00Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "John Doe",
    "email": "[email protected]",
    "timeZone": "America/New_York"
  }
}

すべての予約操作については、references/bookings.md を参照してください。

3. Webhook を設定する

予約イベントのリアルタイム通知を受け取ります:

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

{
  "subscriberUrl": "https://your-app.com/webhook",
  "triggers": ["BOOKING_CREATED", "BOOKING_CANCELLED"]
}

利用可能なトリガーとペイロード形式については、references/webhooks.md を参照してください。

一般的なワークフロー

会議を予約する: スロットを確認 -> 予約を作成 -> 予約 UID を保存

再スケジュール: 新しいスロットを取得 -> POST /v2/bookings/{uid}/reschedule

キャンセル: 任意の理由を付けて POST /v2/bookings/{uid}/cancel

ベストプラクティス

1. 予約を作成する前に必ずスロットの空き状況を確認する
2. 将来の操作（キャンセル、再スケジュール）のために予約 UID を保存する
3. すべてのタイムスタンプに ISO 8601 形式を使用する
4. リアルタイム更新のために Webhook ハンドラーを実装する
5. 指数バックオフでレート制限に対処する

その他のリソース

• 完全な API リファレンス
• OpenAPI 仕様