{"openapi":"3.0.3","info":{"title":"CalMesh API","version":"1.0.0","description":"AI-first calendar aggregation API. Connect Google, Microsoft, Apple, and CalDAV calendars into a single unified API. Includes booking pages, scheduling polls, webhooks, and an official MCP server.","contact":{"name":"CalMesh Support","email":"hello@calmesh.xyz","url":"https://calmesh.xyz"}},"servers":[{"url":"https://calmesh.xyz","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/api-keys":{"post":{"summary":"Create a new API key (returns the full key once)","security":[{"bearerAuth":[]}],"tags":["API Keys"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"User-defined label for the key (min 1, max 100 chars)"},"scope":{"type":"string","description":"Key scope (\"read\" | \"book\" | \"full\" (default: \"full\"))"}},"required":["name"]}}}}},"get":{"summary":"List all API keys (prefix and metadata only)","security":[{"bearerAuth":[]}],"tags":["API Keys"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/api-keys/:id":{"delete":{"summary":"Revoke an API key","security":[{"bearerAuth":[]}],"tags":["API Keys"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/connections":{"get":{"summary":"List all calendar connections for the authenticated user","security":[{"bearerAuth":[]}],"tags":["Calendar Connections"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/connections/google":{"post":{"summary":"Initiate Google Calendar OAuth flow","security":[{"bearerAuth":[]}],"tags":["Calendar Connections"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/connections/microsoft":{"post":{"summary":"Initiate Microsoft Outlook/365 OAuth flow","security":[{"bearerAuth":[]}],"tags":["Calendar Connections"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/connections/icloud":{"post":{"summary":"Connect Apple iCloud Calendar via CalDAV","security":[{"bearerAuth":[]}],"tags":["Calendar Connections"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"appleId":{"type":"string","description":"Apple ID email (valid email)"},"appPassword":{"type":"string","description":"App-specific password (min 1 char)"}},"required":["appleId","appPassword"]}}}}}},"/api/v1/connections/:id":{"get":{"summary":"Get connection details and status","security":[{"bearerAuth":[]}],"tags":["Calendar Connections"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Disconnect a calendar (deletes connection and cached events)","security":[{"bearerAuth":[]}],"tags":["Calendar Connections"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/connections/:id/sync":{"post":{"summary":"Trigger a manual sync for a connection","security":[{"bearerAuth":[]}],"tags":["Calendar Connections"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/calendars":{"post":{"summary":"Create a unified calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Calendar name (min 1, max 100 chars)"},"slug":{"type":"string","description":"URL-safe identifier (lowercase, alphanumeric + hyphens, 3-50 chars)"},"timezone":{"type":"string","description":"IANA timezone (valid IANA timezone)"}},"required":["name","slug","timezone"]}}}}},"get":{"summary":"List all unified calendars","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/calendars/:slug":{"get":{"summary":"Get unified calendar details","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Update a unified calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"Calendar name"},"timezone":{"type":"string","description":"IANA timezone"}}}}}}},"delete":{"summary":"Delete a unified calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/calendars/:slug/sources":{"post":{"summary":"Add a connection to a unified calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","description":"Connection UUID (valid UUID)"}},"required":["connectionId"]}}}}}},"/api/v1/calendars/:slug/sources/reorder":{"patch":{"summary":"Reorder sources within a unified calendar (sort_order determines default write target)","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceIds":{"type":"string","description":"Ordered array of source UUIDs"}},"required":["sourceIds"]}}}}}},"/api/v1/calendars/:slug/sources/:sourceId":{"delete":{"summary":"Remove a connection from a unified calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/calendars/:slug/events":{"post":{"summary":"Create an event on a connected calendar (for AI agents/MCP)","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","description":"Event title (max 500 chars)"},"description":{"type":"string","description":"Event description"},"location":{"type":"string","description":"Event location"},"startTime":{"type":"string","description":"ISO 8601 UTC start (valid datetime)"},"endTime":{"type":"string","description":"ISO 8601 UTC end (after startTime, max 24h)"},"timezone":{"type":"string","description":"IANA timezone"},"sourceId":{"type":"string","description":"Override write target source UUID"}},"required":["summary","startTime","endTime","timezone"]}}}}},"delete":{"summary":"Delete an event from a connected calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"remoteEventId":{"type":"string","description":"Provider event ID"},"sourceId":{"type":"string","description":"Source UUID to delete from"}},"required":["remoteEventId","sourceId"]}}}}},"get":{"summary":"Query merged events from all sources in a unified calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"parameters":[{"name":"start","in":"query","required":true,"description":"Range start (ISO 8601) (valid datetime)","schema":{"type":"string"}},{"name":"end","in":"query","required":true,"description":"Range end (ISO 8601) (valid datetime)","schema":{"type":"string"}},{"name":"timezone","in":"query","required":false,"description":"Display timezone (IANA)","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by status (\"busy\" | \"free\" | \"tentative\" | \"all\")","schema":{"type":"string"}}]}},"/api/v1/calendars/:slug/availability":{"get":{"summary":"Query free/busy availability for a unified calendar","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"parameters":[{"name":"date","in":"query","required":true,"description":"Date to check (YYYY-MM-DD)","schema":{"type":"string"}},{"name":"timezone","in":"query","required":false,"description":"Display timezone (IANA)","schema":{"type":"string"}},{"name":"duration","in":"query","required":false,"description":"Slot duration in minutes (default: 30)","schema":{"type":"integer"}}]}},"/api/v1/calendars/:slug/conflicts":{"get":{"summary":"Detect overlapping events across different sources","security":[{"bearerAuth":[]}],"tags":["Unified Calendars"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"parameters":[{"name":"start","in":"query","required":true,"description":"Range start (ISO 8601)","schema":{"type":"string"}},{"name":"end","in":"query","required":true,"description":"Range end (ISO 8601)","schema":{"type":"string"}}]}},"/api/v1/booking-pages":{"post":{"summary":"Create a booking page attached to a unified calendar","security":[{"bearerAuth":[]}],"tags":["Booking Pages"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"unifiedCalendarId":{"type":"string","description":"Unified calendar UUID (valid UUID)"},"title":{"type":"string","description":"Booking page title (min 1, max 200 chars)"},"slug":{"type":"string","description":"Public URL slug (lowercase, alphanumeric + hyphens, 3-50 chars)"},"durationMinutes":{"type":"integer","description":"Slot duration (default: 30) (5-480)"},"workingHours":{"type":"string","description":"Per-day working hours"},"bufferBefore":{"type":"integer","description":"Buffer before slots (minutes) (0-120)"},"bufferAfter":{"type":"integer","description":"Buffer after slots (minutes) (0-120)"},"minNotice":{"type":"integer","description":"Minimum notice (minutes)"},"maxAdvanceDays":{"type":"integer","description":"Max days ahead to book (1-365)"}},"required":["unifiedCalendarId","title","slug"]}}}}},"get":{"summary":"List all booking pages","security":[{"bearerAuth":[]}],"tags":["Booking Pages"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/booking-pages/:slug":{"get":{"summary":"Get booking page configuration","security":[{"bearerAuth":[]}],"tags":["Booking Pages"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}},"patch":{"summary":"Update a booking page","security":[{"bearerAuth":[]}],"tags":["Booking Pages"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}},"delete":{"summary":"Delete a booking page","security":[{"bearerAuth":[]}],"tags":["Booking Pages"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/booking-pages/:slug/slots":{"get":{"summary":"Get available booking slots (public)","security":[],"tags":["Booking Pages"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"parameters":[{"name":"from","in":"query","required":true,"description":"Range start (ISO 8601 datetime)","schema":{"type":"string"}},{"name":"to","in":"query","required":true,"description":"Range end (ISO 8601 datetime)","schema":{"type":"string"}},{"name":"timezone","in":"query","required":false,"description":"Visitor timezone (IANA)","schema":{"type":"string"}}]}},"/api/v1/booking-pages/:slug/book":{"post":{"summary":"Create a booking (public, visitor submits)","security":[],"tags":["Booking Pages"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"visitorName":{"type":"string","description":"Visitor name (min 1, max 200 chars)"},"visitorEmail":{"type":"string","description":"Visitor email (valid email)"},"visitorTimezone":{"type":"string","description":"Visitor timezone (IANA)"},"startTime":{"type":"string","description":"Slot start time (ISO 8601 datetime)"},"notes":{"type":"string","description":"Optional notes (max 2000 chars)"}},"required":["visitorName","visitorEmail","visitorTimezone","startTime"]}}}}}},"/api/v1/bookings":{"get":{"summary":"List bookings for the authenticated user","security":[{"bearerAuth":[]}],"tags":["Bookings"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/bookings/:id":{"get":{"summary":"Get booking details","security":[{"bearerAuth":[]}],"tags":["Bookings"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/bookings/:id/cancel":{"patch":{"summary":"Cancel a booking (HMAC signature for visitors, auth for owner)","security":[],"tags":["Bookings"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"parameters":[{"name":"sig","in":"query","required":false,"description":"HMAC cancellation signature (for visitor cancellation)","schema":{"type":"string"}}]}},"/api/v1/billing":{"get":{"summary":"Get current subscription status","security":[{"bearerAuth":[]}],"tags":["Billing"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/billing/subscribe":{"post":{"summary":"Initiate Mollie first payment for subscription","security":[{"bearerAuth":[]}],"tags":["Billing"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tier":{"type":"string","description":"Subscription tier (\"agent\" | \"pro\" | \"business\")"}},"required":["tier"]}}}}}},"/api/v1/billing/cancel":{"post":{"summary":"Cancel active subscription","security":[{"bearerAuth":[]}],"tags":["Billing"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/v1/me":{"get":{"summary":"Get current user profile","security":[{"bearerAuth":[]}],"tags":["User"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}},"/api/health":{"get":{"summary":"Health check endpoint","security":[],"tags":["System"],"responses":{"200":{"description":"Success"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"429":{"description":"Rate limited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key (cm_live_...) with scope: read, book, or full"}}}}