cal-com

What this skill does

## Troubleshooting

If requests fail, run `zero doctor check-connector --env-name CALCOM_TOKEN` or `zero doctor check-connector --url https://api.cal.com/v2/me --method GET`

## Core APIs

### Get Current User

```bash
curl -s "https://api.cal.com/v2/me" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '{id, email, name, username, timeZone}'
```

### List Event Types

```bash
curl -s "https://api.cal.com/v2/event-types" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '[.data[] | {id, title, slug, length, hidden}]'
```

### Get Event Type

Replace `<event-type-id>` with the numeric ID from the list above:

```bash
curl -s "https://api.cal.com/v2/event-types/<event-type-id>" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '.data | {id, title, length, description, locations}'
```

### Get Availability

Check available slots for an event type. Replace `<username>` and `<event-type-slug>` with actual values. Dates in `YYYY-MM-DD` format:

```bash
curl -s "https://api.cal.com/v2/slots/available?username=<username>&eventTypeSlug=<event-type-slug>&startTime=2025-01-15&endTime=2025-01-22&timeZone=America/New_York" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '{slots: [.data.slots | to_entries[] | {date: .key, times: [.value[] | .time]}] | .[0:3]}'
```

### Create Booking

Write to `/tmp/calcom_request.json`:

```json
{
  "start": "2025-01-20T14:00:00.000Z",
  "eventTypeId": 123,
  "attendee": {
    "name": "Jane Doe",
    "email": "[email protected]",
    "timeZone": "America/New_York",
    "language": "en"
  },
  "metadata": {
    "source": "clerk_sync"
  }
}
```

```bash
curl -s -X POST "https://api.cal.com/v2/bookings" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" --header "Content-Type: application/json" -d @/tmp/calcom_request.json | jq '{uid, status, start, end, attendees: [.attendees[] | {name, email}]}'
```

Docs: https://cal.com/docs/api-reference/v2/bookings/create-a-booking

### List Bookings

```bash
curl -s "https://api.cal.com/v2/bookings?take=20" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '[.data[] | {uid, status, title, start, end, attendeeName: .attendees[0].name}]'
```

### Get Booking

Replace `<booking-uid>` with the booking UID from the list above:

```bash
curl -s "https://api.cal.com/v2/bookings/<booking-uid>" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" | jq '{uid, status, title, start, end, attendees}'
```

### Cancel Booking

Replace `<booking-uid>` with the booking UID.

Write to `/tmp/calcom_request.json`:

```json
{
  "cancellationReason": "Schedule conflict"
}
```

```bash
curl -s -X DELETE "https://api.cal.com/v2/bookings/<booking-uid>/cancel" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" --header "Content-Type: application/json" -d @/tmp/calcom_request.json | jq '{status}'
```

### Reschedule Booking

Replace `<booking-uid>` with the booking UID.

Write to `/tmp/calcom_request.json`:

```json
{
  "start": "2025-01-22T15:00:00.000Z",
  "reschedulingReason": "Attendee requested different time"
}
```

```bash
curl -s -X POST "https://api.cal.com/v2/bookings/<booking-uid>/reschedule" --header "Authorization: Bearer $CALCOM_TOKEN" --header "cal-api-version: 2024-08-13" --header "Content-Type: application/json" -d @/tmp/calcom_request.json | jq '{uid, status, start, end}'
```

## Guidelines

1. **API version header**: Always include `cal-api-version: 2024-08-13` — requests without this header will fail.
2. **API key prefix**: Cal.com API keys are prefixed with `cal_live_` (production) or `cal_test_` (test environment).
3. **eventTypeId**: Required when creating a booking — get it from the List Event Types endpoint.
4. **Timestamps**: Use ISO 8601 format with UTC timezone (e.g., `2025-01-20T14:00:00.000Z`).
5. **Rate limits**: 120 requests per minute with API key auth. Response headers include `X-RateLimit-Remaining`.
6. **Self-hosted**: If using a self-hosted Cal.com instance, replace `api.cal.com` with your own domain.
7. **Booking confirmation**: If an event type requires manual confirmation, bookings start with `pending` status until confirmed.