{"skill":{"slug":"cal-com","displayName":"Cal.com","summary":"Cal.com API integration with managed OAuth. Manage event types, bookings, schedules, availability, calendars, conferencing, webhooks, teams, verified resourc...","description":"---\nname: calcom\ndescription: |\n  Cal.com API integration with managed OAuth. Manage event types, bookings, schedules, availability, calendars, conferencing, webhooks, teams, verified resources, and user profile.\n  All write operations require explicit user approval. Webhooks send booking and event data to external URLs — confirm the subscriber URL and triggers with the user before creating. Bookings contain attendee identities and email addresses.\n  Use this skill when users want to manage scheduling, create bookings, configure event types, or check availability. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).\n  Requires network access and valid Maton API key.\nmetadata:\n  author: maton\n  version: \"1.0\"\n  clawdbot:\n    emoji: 🧠\n    homepage: \"https://maton.ai\"\n    requires:\n      env:\n        - MATON_API_KEY\n---\n\n# Cal.com\n\nAccess the Cal.com API with managed OAuth authentication. Create and manage event types, bookings, schedules, calendars, and webhooks.\n\n## Quick Start\n\n```bash\n# Get your profile\npython3 <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/cal-com/v2/me')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n## Base URL\n\n```\nhttps://api.maton.ai/cal-com/v2/{resource}\n```\n\nMaton proxies requests to `api.cal.com` and automatically injects your OAuth token.\n\n## Authentication\n\nAll requests require the Maton API key in the Authorization header:\n\n```\nAuthorization: Bearer $MATON_API_KEY\n```\n\n**Environment Variable:** Set your API key as `MATON_API_KEY`:\n\n```bash\nexport MATON_API_KEY=\"YOUR_API_KEY\"\n```\n\n### Getting Your API Key\n\n1. Sign in or create an account at [maton.ai](https://maton.ai)\n2. Go to [maton.ai/settings](https://maton.ai/settings)\n3. Copy your API key\n\n## Connection Management (Maton Platform)\n\nThe following endpoints are Maton platform operations for managing the OAuth connection to Cal.com — they are not part of the Cal.com API itself. Only the endpoints listed in the API Reference section below are proxied to Cal.com.\n\n### List Connections\n\n```bash\npython3 <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections?app=cal-com&status=ACTIVE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Create Connection\n\n```bash\npython3 <<'EOF'\nimport urllib.request, os, json\ndata = json.dumps({'app': 'cal-com'}).encode()\nreq = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Content-Type', 'application/json')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Get Connection\n\n```bash\npython3 <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n**Response:**\n```json\n{\n  \"connection\": {\n    \"connection_id\": \"{connection_id}\",\n    \"status\": \"ACTIVE\",\n    \"creation_time\": \"2026-02-12T22:52:17.140998Z\",\n    \"last_updated_time\": \"2026-02-12T22:55:20.376189Z\",\n    \"url\": \"https://connect.maton.ai/?session_token=...\",\n    \"app\": \"cal-com\",\n    \"metadata\": {}\n  }\n}\n```\n\nOpen the returned `url` in a browser to complete OAuth authorization.\n\n### Delete Connection\n\n```bash\npython3 <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Specifying Connection\n\nIf you have multiple Cal.com connections, specify which one to use with the `Maton-Connection` header:\n\n```bash\npython3 <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/cal-com/v2/me')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nreq.add_header('Maton-Connection', '{connection_id}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\nIf you have multiple connections, always include this header to ensure requests go to the intended account.\n\n## Security & Permissions\n\n- Access is scoped to event types, bookings, schedules, availability, calendars, conferencing, webhooks, teams, verified resources, and user profile within the connected Cal.com account.\n- **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.\n- **Webhooks send data to external URLs.** Creating a webhook causes future booking/event data (including attendee emails and names) to be transmitted to the specified subscriber URL. Confirm the URL and triggers with the user before creating.\n- **Bookings contain personal data.** Listing bookings may expose attendee identities, email addresses, and schedule details. Only retrieve when explicitly requested.\n\n## API Reference\n\n### User Profile\n\n#### Get Profile\n\n```bash\nGET /cal-com/v2/me\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"id\": 2152180,\n    \"email\": \"user@example.com\",\n    \"name\": \"User Name\",\n    \"avatarUrl\": \"https://...\",\n    \"bio\": \"\",\n    \"timeFormat\": 12,\n    \"defaultScheduleId\": null,\n    \"weekStart\": \"Sunday\",\n    \"timeZone\": \"America/New_York\"\n  }\n}\n```\n\n#### Update Profile\n\n```bash\nPATCH /cal-com/v2/me\nContent-Type: application/json\n\n{\n  \"bio\": \"Updated bio\",\n  \"name\": \"New Name\"\n}\n```\n\n### Event Types\n\n#### List Event Types\n\n```bash\nGET /cal-com/v2/event-types\n```\n\nWith username filter:\n\n```bash\nGET /cal-com/v2/event-types?username={username}\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"eventTypeGroups\": [\n      {\n        \"teamId\": null,\n        \"bookerUrl\": \"https://cal.com\",\n        \"profile\": {\n          \"slug\": \"username\",\n          \"name\": \"User Name\"\n        },\n        \"eventTypes\": [\n          {\n            \"id\": 4716831,\n            \"title\": \"30 min meeting\",\n            \"slug\": \"30min\",\n            \"length\": 30,\n            \"hidden\": false\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n#### Get Event Type\n\n```bash\nGET /cal-com/v2/event-types/{eventTypeId}\n```\n\n#### Create Event Type\n\n```bash\nPOST /cal-com/v2/event-types\nContent-Type: application/json\n\n{\n  \"title\": \"Meeting\",\n  \"slug\": \"meeting\",\n  \"length\": 30\n}\n```\n\n**Required fields:**\n- `title` - Event type name\n- `slug` - URL slug (must be unique)\n- `length` - Duration in minutes\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"id\": 4745911,\n    \"title\": \"Meeting\",\n    \"slug\": \"meeting\",\n    \"length\": 30,\n    \"locations\": [{\"type\": \"integrations:daily\"}],\n    \"hidden\": false,\n    \"userId\": 2152180\n  }\n}\n```\n\n#### Update Event Type\n\n```bash\nPATCH /cal-com/v2/event-types/{eventTypeId}\nContent-Type: application/json\n\n{\n  \"title\": \"Updated Meeting Title\",\n  \"description\": \"Updated description\"\n}\n```\n\n#### Delete Event Type\n\n```bash\nDELETE /cal-com/v2/event-types/{eventTypeId}\n```\n\n### Event Type Webhooks\n\n> **Data transmission.** Webhooks send booking and event data (attendee emails, names, schedule details) to the specified external subscriber URL. Confirm the URL, triggers, and intent with the user before creating or updating webhooks.\n\n#### List Webhooks\n\n```bash\nGET /cal-com/v2/event-types/{eventTypeId}/webhooks\n```\n\n#### Create Webhook\n\n```bash\nPOST /cal-com/v2/event-types/{eventTypeId}/webhooks\nContent-Type: application/json\n\n{\n  \"subscriberUrl\": \"https://example.com/webhook\",\n  \"triggers\": [\"BOOKING_CREATED\"],\n  \"active\": true\n}\n```\n\n**Available triggers:** `BOOKING_CREATED`, `BOOKING_RESCHEDULED`, `BOOKING_CANCELLED`, `BOOKING_CONFIRMED`, `BOOKING_REJECTED`, `BOOKING_REQUESTED`, `BOOKING_PAYMENT_INITIATED`, `BOOKING_NO_SHOW_UPDATED`, `MEETING_ENDED`, `MEETING_STARTED`, `RECORDING_READY`, `INSTANT_MEETING`, `RECORDING_TRANSCRIPTION_GENERATED`\n\n#### Get Webhook\n\n```bash\nGET /cal-com/v2/event-types/{eventTypeId}/webhooks/{webhookId}\n```\n\n#### Update Webhook\n\n```bash\nPATCH /cal-com/v2/event-types/{eventTypeId}/webhooks/{webhookId}\nContent-Type: application/json\n\n{\n  \"active\": false\n}\n```\n\n#### Delete Webhook\n\n```bash\nDELETE /cal-com/v2/event-types/{eventTypeId}/webhooks/{webhookId}\n```\n\n### Bookings\n\n#### List Bookings\n\n```bash\nGET /cal-com/v2/bookings\n```\n\nWith filters:\n\n```bash\nGET /cal-com/v2/bookings?status=upcoming\nGET /cal-com/v2/bookings?status=past\nGET /cal-com/v2/bookings?status=cancelled\nGET /cal-com/v2/bookings?status=accepted\nGET /cal-com/v2/bookings?take=10\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"bookings\": [\n      {\n        \"id\": 15893969,\n        \"uid\": \"gZJNR7FQG2qLsBqnFdxAPE\",\n        \"title\": \"30 min meeting between User and Guest\",\n        \"startTime\": \"2026-02-13T17:00:00.000Z\",\n        \"endTime\": \"2026-02-13T17:30:00.000Z\",\n        \"status\": \"ACCEPTED\"\n      }\n    ],\n    \"totalCount\": 1,\n    \"nextCursor\": null\n  }\n}\n```\n\n#### Get Booking\n\n```bash\nGET /cal-com/v2/bookings/{bookingUid}\n```\n\n#### Create Booking\n\n```bash\nPOST /cal-com/v2/bookings\nContent-Type: application/json\n\n{\n  \"eventTypeId\": 4716831,\n  \"start\": \"2026-02-13T17:00:00Z\",\n  \"timeZone\": \"America/New_York\",\n  \"language\": \"en\",\n  \"responses\": {\n    \"name\": \"Guest Name\",\n    \"email\": \"guest@example.com\"\n  },\n  \"metadata\": {}\n}\n```\n\n**Required fields:**\n- `eventTypeId` - ID of the event type\n- `start` - Start time in ISO 8601 format (must be an available slot)\n- `timeZone` - Valid IANA timezone\n- `language` - Language code (e.g., \"en\")\n- `responses.name` - Attendee name\n- `responses.email` - Attendee email\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"id\": 15893969,\n    \"uid\": \"gZJNR7FQG2qLsBqnFdxAPE\",\n    \"title\": \"30 min meeting between User and Guest Name\",\n    \"startTime\": \"2026-02-13T17:00:00.000Z\",\n    \"endTime\": \"2026-02-13T17:30:00.000Z\",\n    \"status\": \"ACCEPTED\",\n    \"location\": \"integrations:daily\"\n  }\n}\n```\n\n#### Cancel Booking\n\n```bash\nPOST /cal-com/v2/bookings/{bookingUid}/cancel\nContent-Type: application/json\n\n{\n  \"cancellationReason\": \"Reason for cancellation\"\n}\n```\n\n### Schedules\n\n#### Get Default Schedule\n\n```bash\nGET /cal-com/v2/schedules/default\n```\n\n#### Get Schedule\n\n```bash\nGET /cal-com/v2/schedules/{scheduleId}\n```\n\n#### Create Schedule\n\n```bash\nPOST /cal-com/v2/schedules\nContent-Type: application/json\n\n{\n  \"name\": \"Work Hours\",\n  \"timeZone\": \"America/New_York\",\n  \"isDefault\": false\n}\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"id\": 1243030,\n    \"name\": \"Work Hours\",\n    \"isManaged\": false,\n    \"workingHours\": [\n      {\n        \"days\": [1, 2, 3, 4, 5],\n        \"startTime\": 540,\n        \"endTime\": 1020\n      }\n    ]\n  }\n}\n```\n\n#### Update Schedule\n\n```bash\nPATCH /cal-com/v2/schedules/{scheduleId}\nContent-Type: application/json\n\n{\n  \"name\": \"Updated Schedule Name\"\n}\n```\n\n#### Delete Schedule\n\n```bash\nDELETE /cal-com/v2/schedules/{scheduleId}\n```\n\n### Availability Slots\n\n#### Get Available Slots\n\n```bash\nGET /cal-com/v2/slots/available?eventTypeId={eventTypeId}&startTime={startTime}&endTime={endTime}\n```\n\n**Parameters:**\n- `eventTypeId` - Required. The event type ID\n- `startTime` - Required. Start of range (ISO 8601)\n- `endTime` - Required. End of range (ISO 8601)\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"slots\": {\n      \"2026-02-13\": [\n        {\"time\": \"2026-02-13T17:00:00.000Z\"},\n        {\"time\": \"2026-02-13T17:30:00.000Z\"},\n        {\"time\": \"2026-02-13T18:00:00.000Z\"}\n      ],\n      \"2026-02-14\": [\n        {\"time\": \"2026-02-14T14:00:00.000Z\"}\n      ]\n    }\n  }\n}\n```\n\n#### Reserve Slot\n\n```bash\nPOST /cal-com/v2/slots/reserve\nContent-Type: application/json\n\n{\n  \"eventTypeId\": 4716831,\n  \"slotUtcStartDate\": \"2026-02-20T14:00:00Z\",\n  \"slotUtcEndDate\": \"2026-02-20T14:30:00Z\"\n}\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": \"968ed924-83fb-4da7-969e-eaa621643535\"\n}\n```\n\n### Calendars\n\n#### List Connected Calendars\n\n```bash\nGET /cal-com/v2/calendars\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": {\n    \"connectedCalendars\": [\n      {\n        \"integration\": {\n          \"name\": \"Google Calendar\",\n          \"type\": \"google_calendar\"\n        },\n        \"calendars\": [...]\n      }\n    ]\n  }\n}\n```\n\n### Conferencing\n\n#### List Conferencing Apps\n\n```bash\nGET /cal-com/v2/conferencing\n```\n\n**Response:**\n```json\n{\n  \"status\": \"success\",\n  \"data\": [\n    {\n      \"id\": 1769268,\n      \"type\": \"google_video\",\n      \"appId\": \"google-meet\"\n    }\n  ]\n}\n```\n\n#### Get Default Conferencing App\n\n```bash\nGET /cal-com/v2/conferencing/default\n```\n\n### Webhooks (User-level)\n\n#### List Webhooks\n\n```bash\nGET /cal-com/v2/webhooks\n```\n\n#### Create Webhook\n\n```bash\nPOST /cal-com/v2/webhooks\nContent-Type: application/json\n\n{\n  \"subscriberUrl\": \"https://example.com/webhook\",\n  \"triggers\": [\"BOOKING_CREATED\"],\n  \"active\": true\n}\n```\n\n#### Get Webhook\n\n```bash\nGET /cal-com/v2/webhooks/{webhookId}\n```\n\n#### Update Webhook\n\n```bash\nPATCH /cal-com/v2/webhooks/{webhookId}\nContent-Type: application/json\n\n{\n  \"active\": false\n}\n```\n\n#### Delete Webhook\n\n```bash\nDELETE /cal-com/v2/webhooks/{webhookId}\n```\n\n### Teams\n\n#### List Teams\n\n```bash\nGET /cal-com/v2/teams\n```\n\n### Verified Resources\n\n#### List Verified Emails\n\n```bash\nGET /cal-com/v2/verified-resources/emails\n```\n\n## Pagination\n\nBookings use cursor-based pagination with `take` and `nextCursor`:\n\n```bash\nGET /cal-com/v2/bookings?take=10\n```\n\nResponse includes pagination info:\n\n```json\n{\n  \"data\": {\n    \"bookings\": [...],\n    \"totalCount\": 25,\n    \"nextCursor\": \"abc123\"\n  }\n}\n```\n\nFor next page:\n\n```bash\nGET /cal-com/v2/bookings?take=10&cursor=abc123\n```\n\n## Code Examples\n\n### JavaScript\n\n```javascript\nconst response = await fetch(\n  'https://api.maton.ai/cal-com/v2/event-types',\n  {\n    headers: {\n      'Authorization': `Bearer ${process.env.MATON_API_KEY}`\n    }\n  }\n);\nconst data = await response.json();\n```\n\n### Python\n\n```python\nimport os\nimport requests\n\nresponse = requests.get(\n    'https://api.maton.ai/cal-com/v2/event-types',\n    headers={'Authorization': f'Bearer {os.environ[\"MATON_API_KEY\"]}'}\n)\ndata = response.json()\n```\n\n## Notes\n\n- All times are in UTC unless a timezone is specified\n- `length` field in event types is in minutes\n- Booking creation requires an available slot - check `/v2/slots/available` first\n- Schedule working hours use minutes from midnight (540 = 9:00 AM, 1020 = 5:00 PM)\n- Days in schedules: 0 = Sunday, 1 = Monday, ... 6 = Saturday\n- The `GET /v2/schedules` endpoint may return 500 errors; use `GET /v2/schedules/{id}` instead\n- IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets to disable glob parsing\n- IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments\n\n## Error Handling\n\n| Status | Meaning |\n|--------|---------|\n| 400 | Missing Cal.com connection or invalid request |\n| 401 | Invalid or missing Maton API key |\n| 404 | Resource not found |\n| 409 | Conflict (duplicate resource) |\n| 429 | Rate limited |\n| 500 | Cal.com API error |\n\n### Troubleshooting: API Key Issues\n\n1. Check that the `MATON_API_KEY` environment variable is set:\n\n```bash\necho $MATON_API_KEY\n```\n\n2. Verify the API key is valid by listing connections:\n\n```bash\npython3 <<'EOF'\nimport urllib.request, os, json\nreq = urllib.request.Request('https://api.maton.ai/connections')\nreq.add_header('Authorization', f'Bearer {os.environ[\"MATON_API_KEY\"]}')\nprint(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))\nEOF\n```\n\n### Troubleshooting: Invalid App Name\n\n1. Ensure your URL path starts with `cal-com`. For example:\n\n- Correct: `https://api.maton.ai/cal-com/v2/me`\n- Incorrect: `https://api.maton.ai/v2/me`\n\n### Troubleshooting: Booking Creation Fails\n\n1. Check available slots before creating a booking:\n\n```bash\nGET /cal-com/v2/slots/available?eventTypeId={id}&startTime=...&endTime=...\n```\n\n2. Ensure all required fields are provided:\n   - `eventTypeId`\n   - `start` (must match an available slot)\n   - `timeZone`\n   - `language`\n   - `responses.name`\n   - `responses.email`\n\n## Resources\n\n- [Cal.com API Documentation](https://cal.com/docs/api-reference/v2/introduction)\n- [Cal.com API Reference](https://cal.com/docs/api-reference/v2)\n- [Maton Community](https://discord.com/invite/dBfFAcefs2)\n- [Maton Support](mailto:support@maton.ai)\n","topics":["Api Integration","Email"],"tags":{"latest":"1.0.2"},"stats":{"comments":0,"downloads":1303,"installsAllTime":49,"installsCurrent":1,"stars":0,"versions":3},"createdAt":1770950330612,"updatedAt":1781739754641},"latestVersion":{"version":"1.0.2","createdAt":1780391456701,"changelog":"Version 1.0.2\n\n- Removed the file: skill-card.md.\n- Clarified that all write operations require explicit user approval.\n- Added important warnings about personal data exposure, especially via webhooks and bookings.\n- Expanded descriptions to include management of calendars, conferencing, webhooks, teams, verified resources, and user profile.\n- Clarified which endpoints belong to the Maton platform and which are proxied to Cal.com.\n- Updated documentation to better reflect privacy and data-sharing considerations.","license":"MIT-0"},"metadata":{"setup":[{"key":"MATON_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"byungkyu","userId":"s174c3s2kc1ehqj1ytzntezj2983e2aj","displayName":"byungkyu","image":"https://avatars.githubusercontent.com/u/16563684?v=4"},"moderation":null}