Cal Api

Cal.com provides a REST API (v2) for programmatic scheduling, making it practical for agents that need to handle booking flows. Agents can create bookings on behalf of users, query available time slots, cancel or reschedule meetings, and receive webhook events for booking lifecycle changes (created, rescheduled, cancelled). Event types, schedules, and team availability are all API-accessible. Cal.com is open-source (AGPL) with a managed cloud option and self-hosting support. The v2 API is the stable surface; v1 is legacy. Authentication supports both API keys and OAuth2. Confidence is docs-derived; webhook reliability and rate limits are not runtime-verified.

Authentication supports two patterns: API key (passed as cal-api-key header) for machine-to-machine, and OAuth2 for delegated user access. API keys are per-user, generated in Cal.com dashboard. OAuth2 is available for third-party integrations. Managed accounts support organization-level admin keys. Token scopes are documented for OAuth. Straightforward for agent use with API key auth.

Documentation at cal.com/docs/api-reference/v2 is detailed with endpoint reference, authentication guide, and webhook event types. Examples are provided for common workflows. The API playground is available for testing. Self-hosting documentation is comprehensive. Community support via GitHub Discussions and Discord. Documentation quality is high for the core booking API; some edge cases in team scheduling are less documented.

The Cal.com v2 REST API follows RESTful conventions: /bookings, /event-types, /schedules, /slots. JSON request/response. Cursor-based pagination. Endpoint coverage is comprehensive: slots availability, booking creation with attendee info, reschedule, cancel, and team booking. The API returns detailed booking objects including calendar event IDs and conferencing links. Rate limits are documented (plan-dependent). SDK support is available for TypeScript. The API versioning is explicit (v2 stable, v1 deprecated).

Cal.com API returns standard HTTP error codes: 400 for validation errors, 401 for auth failures, 404 for not-found resources, 422 for business logic errors (e.g., no available slots), 429 for rate limits with retry-after header. Error bodies include a message field and error code. Booking conflicts return structured errors with available alternatives. Webhook delivery includes retry logic on failure. Error handling is well-designed for agent consumption.