Calendly
name: calendly
by byungkyu · published 2026-03-22
$ claw add gh:byungkyu/byungkyu-calendly-api---
name: calendly
description: |
Calendly API integration with managed OAuth. Access event types, scheduled events, invitees, availability, and manage webhooks. Use this skill when users want to view scheduling data, check availability, book meetings, or integrate with Calendly workflows. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
author: maton
version: "1.0"
clawdbot:
emoji: 🧠
requires:
env:
- MATON_API_KEY
---
# Calendly
Access the Calendly API with managed OAuth authentication. Retrieve event types, scheduled events, invitees, availability data, and manage webhook subscriptions for scheduling automation.
Quick Start
# Get current user
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/users/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFBase URL
https://gateway.maton.ai/calendly/{native-api-path}Replace `{native-api-path}` with the actual Calendly API endpoint path. The gateway proxies requests to `api.calendly.com` and automatically injects your OAuth token.
Authentication
All requests require the Maton API key in the Authorization header:
Authorization: Bearer $MATON_API_KEY**Environment Variable:** Set your API key as `MATON_API_KEY`:
export MATON_API_KEY="YOUR_API_KEY"Getting Your API Key
1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key
Connection Management
Manage your Calendly OAuth connections at `https://ctrl.maton.ai`.
List Connections
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=calendly&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFCreate Connection
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'calendly'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFGet Connection
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"connection": {
"connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
"status": "ACTIVE",
"creation_time": "2025-12-08T07:20:53.488460Z",
"last_updated_time": "2026-01-31T20:03:32.593153Z",
"url": "https://connect.maton.ai/?session_token=...",
"app": "calendly",
"metadata": {}
}
}Open the returned `url` in a browser to complete OAuth authorization.
Delete Connection
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFSpecifying Connection
If you have multiple Calendly connections, specify which one to use with the `Maton-Connection` header:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/users/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFIf omitted, the gateway uses the default (oldest) active connection.
API Reference
Users
#### Get Current User
GET /calendly/users/me**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/users/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"resource": {
"uri": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA",
"name": "Alice Johnson",
"slug": "alice-johnson",
"email": "alice.johnson@acme.com",
"scheduling_url": "https://calendly.com/alice-johnson",
"timezone": "America/New_York",
"avatar_url": "https://example.com/avatar.png",
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2025-06-20T14:45:00.000000Z",
"current_organization": "https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB"
}
}#### Get a User
GET /calendly/users/{uuid}Event Types
#### List Event Types
GET /calendly/event_typesQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/event_types?user=https://api.calendly.com/users/AAAAAAAAAAAAAAAA&active=true')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"collection": [
{
"uri": "https://api.calendly.com/event_types/CCCCCCCCCCCCCCCC",
"name": "30 Minute Meeting",
"active": true,
"slug": "30min",
"scheduling_url": "https://calendly.com/alice-johnson/30min",
"duration": 30,
"kind": "solo",
"type": "StandardEventType",
"color": "#0066FF",
"created_at": "2024-02-01T09:00:00.000000Z",
"updated_at": "2025-05-15T11:30:00.000000Z",
"description_plain": "A quick 30-minute catch-up call",
"description_html": "<p>A quick 30-minute catch-up call</p>",
"profile": {
"type": "User",
"name": "Alice Johnson",
"owner": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA"
}
}
],
"pagination": {
"count": 1,
"next_page_token": null
}
}#### Get an Event Type
GET /calendly/event_types/{uuid}Scheduled Events
#### List Scheduled Events
GET /calendly/scheduled_eventsQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/scheduled_events?user=https://api.calendly.com/users/AAAAAAAAAAAAAAAA&status=active&min_start_time=2025-03-01T00:00:00Z')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"collection": [
{
"uri": "https://api.calendly.com/scheduled_events/DDDDDDDDDDDDDDDD",
"name": "30 Minute Meeting",
"status": "active",
"start_time": "2025-03-15T14:00:00.000000Z",
"end_time": "2025-03-15T14:30:00.000000Z",
"event_type": "https://api.calendly.com/event_types/CCCCCCCCCCCCCCCC",
"location": {
"type": "zoom",
"join_url": "https://zoom.us/j/123456789"
},
"invitees_counter": {
"total": 1,
"active": 1,
"limit": 1
},
"created_at": "2025-03-10T09:15:00.000000Z",
"updated_at": "2025-03-10T09:15:00.000000Z",
"event_memberships": [
{
"user": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA"
}
]
}
],
"pagination": {
"count": 1,
"next_page_token": null
}
}#### Get a Scheduled Event
GET /calendly/scheduled_events/{uuid}#### Cancel a Scheduled Event
POST /calendly/scheduled_events/{uuid}/cancellation
Content-Type: application/json
{
"reason": "Meeting rescheduled"
}**Example:**
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'reason': 'Meeting rescheduled'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/calendly/scheduled_events/DDDDDDDDDDDDDDDD/cancellation', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFInvitees
#### List Event Invitees
GET /calendly/scheduled_events/{event_uuid}/inviteesQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/scheduled_events/DDDDDDDDDDDDDDDD/invitees')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"collection": [
{
"uri": "https://api.calendly.com/scheduled_events/DDDDDDDDDDDDDDDD/invitees/EEEEEEEEEEEEEEEE",
"email": "bob.smith@example.com",
"name": "Bob Smith",
"status": "active",
"timezone": "America/Los_Angeles",
"event": "https://api.calendly.com/scheduled_events/DDDDDDDDDDDDDDDD",
"created_at": "2025-03-10T09:15:00.000000Z",
"updated_at": "2025-03-10T09:15:00.000000Z",
"questions_and_answers": [
{
"question": "What would you like to discuss?",
"answer": "Project timeline review",
"position": 0
}
],
"tracking": {
"utm_source": null,
"utm_medium": null,
"utm_campaign": null
},
"cancel_url": "https://calendly.com/cancellations/EEEEEEEEEEEEEEEE",
"reschedule_url": "https://calendly.com/reschedulings/EEEEEEEEEEEEEEEE"
}
],
"pagination": {
"count": 1,
"next_page_token": null
}
}#### Get an Invitee
GET /calendly/scheduled_events/{event_uuid}/invitees/{invitee_uuid}#### Create Event Invitee (Scheduling API)
Schedule a meeting programmatically by creating an invitee. Requires a paid Calendly plan.
POST /calendly/event_types/{event_type_uuid}/invitees
Content-Type: application/json
{
"start_time": "2025-03-20T15:00:00Z",
"email": "bob.smith@example.com",
"name": "Bob Smith",
"timezone": "America/Los_Angeles",
"location": {
"kind": "zoom"
},
"questions_and_answers": [
{
"question_uuid": "QQQQQQQQQQQQQQQ",
"answer": "Project timeline review"
}
]
}**Example:**
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'start_time': '2025-03-20T15:00:00Z', 'email': 'bob.smith@example.com', 'name': 'Bob Smith'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/calendly/event_types/CCCCCCCCCCCCCCCC/invitees', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Note:** The `start_time` must correspond to a valid available slot. Use the `/event_type_available_times` endpoint to find available times.
Availability
#### Get Event Type Available Times
GET /calendly/event_type_available_timesQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/event_type_available_times?event_type=https://api.calendly.com/event_types/CCCCCCCCCCCCCCCC&start_time=2025-03-15T00:00:00Z&end_time=2025-03-22T00:00:00Z')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"collection": [
{
"status": "available",
"invitees_remaining": 1,
"start_time": "2025-03-17T14:00:00.000000Z",
"scheduling_url": "https://calendly.com/alice-johnson/30min/2025-03-17T14:00:00Z"
},
{
"status": "available",
"invitees_remaining": 1,
"start_time": "2025-03-17T14:30:00.000000Z",
"scheduling_url": "https://calendly.com/alice-johnson/30min/2025-03-17T14:30:00Z"
}
]
}#### Get User Busy Times
GET /calendly/user_busy_timesQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/user_busy_times?user=https://api.calendly.com/users/AAAAAAAAAAAAAAAA&start_time=2025-03-15T00:00:00Z&end_time=2025-03-22T00:00:00Z')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"collection": [
{
"type": "calendly",
"start_time": "2025-03-17T10:00:00.000000Z",
"end_time": "2025-03-17T11:00:00.000000Z"
},
{
"type": "external",
"start_time": "2025-03-18T14:00:00.000000Z",
"end_time": "2025-03-18T15:00:00.000000Z"
}
]
}#### Get User Availability Schedules
GET /calendly/user_availability_schedulesQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/user_availability_schedules?user=https://api.calendly.com/users/AAAAAAAAAAAAAAAA')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFOrganization
#### List Organization Memberships
GET /calendly/organization_membershipsQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/organization_memberships?organization=https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"collection": [
{
"uri": "https://api.calendly.com/organization_memberships/FFFFFFFFFFFFFFFF",
"role": "admin",
"user": {
"uri": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA",
"name": "Alice Johnson",
"email": "alice.johnson@acme.com"
},
"organization": "https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB",
"created_at": "2024-01-15T10:30:00.000000Z",
"updated_at": "2025-06-20T14:45:00.000000Z"
}
],
"pagination": {
"count": 1,
"next_page_token": null
}
}Webhooks
Webhooks require a paid Calendly plan (Standard, Teams, or Enterprise).
#### List Webhook Subscriptions
GET /calendly/webhook_subscriptionsQuery parameters:
**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/webhook_subscriptions?organization=https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB&scope=organization')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF#### Create Webhook Subscription
POST /calendly/webhook_subscriptions
Content-Type: application/json
{
"url": "https://example.com/webhook",
"events": ["invitee.created", "invitee.canceled"],
"organization": "https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB",
"scope": "organization",
"signing_key": "your-secret-key"
}Available events:
**Example:**
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'url': 'https://example.com/webhook', 'events': ['invitee.created', 'invitee.canceled'], 'organization': 'https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB', 'scope': 'organization'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/calendly/webhook_subscriptions', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF**Response:**
{
"resource": {
"uri": "https://api.calendly.com/webhook_subscriptions/GGGGGGGGGGGGGGGG",
"callback_url": "https://example.com/webhook",
"created_at": "2025-03-01T12:00:00.000000Z",
"updated_at": "2025-03-01T12:00:00.000000Z",
"retry_started_at": null,
"state": "active",
"events": ["invitee.created", "invitee.canceled"],
"scope": "organization",
"organization": "https://api.calendly.com/organizations/BBBBBBBBBBBBBBBB",
"user": null,
"creator": "https://api.calendly.com/users/AAAAAAAAAAAAAAAA"
}
}#### Get a Webhook Subscription
GET /calendly/webhook_subscriptions/{uuid}#### Delete a Webhook Subscription
DELETE /calendly/webhook_subscriptions/{uuid}**Example:**
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/webhook_subscriptions/GGGGGGGGGGGGGGGG', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFReturns `204 No Content` on success.
Pagination
Use `page_token` for pagination. Response includes `pagination.next_page_token` when more results exist:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/calendly/scheduled_events?user=USER_URI&page_token=NEXT_PAGE_TOKEN')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFCode Examples
JavaScript
const response = await fetch(
'https://gateway.maton.ai/calendly/scheduled_events?user=https://api.calendly.com/users/AAAAAAAAAAAAAAAA&status=active',
{
headers: {
'Authorization': `Bearer ${process.env.MATON_API_KEY}`
}
}
);
const data = await response.json();Python
import os
import requests
response = requests.get(
'https://gateway.maton.ai/calendly/scheduled_events',
headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
params={
'user': 'https://api.calendly.com/users/AAAAAAAAAAAAAAAA',
'status': 'active'
}
)
data = response.json()Notes
Error Handling
| Status | Meaning |
|--------|---------|
| 400 | Bad request or missing Calendly connection |
| 401 | Invalid or missing Maton API key |
| 403 | Forbidden - insufficient permissions or plan restrictions |
| 404 | Resource not found |
| 424 | External calendar error (calendar integration issue on Calendly side) |
| 429 | Rate limited |
| 4xx/5xx | Passthrough error from Calendly API |
Troubleshooting: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
echo $MATON_API_KEY2. Verify the API key is valid by listing connections:
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOFTroubleshooting: Invalid App Name
1. Ensure your URL path starts with `calendly`. For example:
Resources
More tools from the same signal band
Order food/drinks (点餐) on an Android device paired as an OpenClaw node. Uses in-app menu and cart; add goods, view cart, submit order (demo, no real payment).
Sign plugins, rotate agent credentials without losing identity, and publicly attest to plugin behavior with verifiable claims and authenticated transfers.
The philosophical layer for AI agents. Maps behavior to Spinoza's 48 affects, calculates persistence scores, and generates geometric self-reports. Give your...