# AI agents Source: https://cal.com/docs/agents How AI agents can use the Cal.com API v2 to manage scheduling This guide explains how to build AI agents that interact with Cal.com's scheduling infrastructure. ## Recommended: Use the Cal.com CLI For agents that can execute commands on a machine, use the official Cal.com CLI instead of calling the API directly. The CLI handles authentication, versioning, and common workflows automatically. ```bash theme={null} npm install -g @calcom/cli ``` ```bash theme={null} curl -fsSL https://cal.com/install.sh | bash ``` The CLI includes `--help` flags on all commands to learn about available options: ```bash theme={null} calcom --help calcom bookings --help calcom slots --help ``` Only fall back to the API approach below if your agent cannot install or execute the CLI on its machine. ## Overview Cal.com API v2 enables AI agents to: * **Check availability** - Query available time slots for any user or team * **Create bookings** - Schedule meetings on behalf of users * **Manage event types** - Create and configure different meeting types * **Handle rescheduling and cancellations** - Modify existing bookings * **Manage schedules** - Set and update user availability * **Track credit usage** - Check balances and charge credits for agent interactions ## Authentication AI agents should authenticate using an **API key**. Generate one in [Settings → Developer → API Keys](https://app.cal.com/settings/developer/api-keys). ```bash theme={null} curl -X GET "https://api.cal.com/v2/me" \ -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \ -H "cal-api-version: 2024-08-13" ``` The `cal-api-version` header is required for all v2 endpoints. If you omit it, requests will return a 404. Always include `cal-api-version: 2024-08-13`. ## Common workflows ### 1. Check availability Query available slots using username and event slug—no need to look up IDs first: ```bash theme={null} curl -X GET "https://api.cal.com/v2/slots?username=bailey&eventSlug=15min&startTime=2024-01-15T00:00:00Z&endTime=2024-01-16T23:59:59Z" \ -H "cal-api-version: 2024-08-13" ``` Response includes available time slots: ```json theme={null} { "status": "success", "data": { "slots": { "2024-01-15": [ { "time": "2024-01-15T09:00:00Z" }, { "time": "2024-01-15T10:00:00Z" }, { "time": "2024-01-15T14:00:00Z" } ] } } } ``` ### 2. Create a booking Schedule a meeting using username and event slug. This is the most common pattern for AI agents that extract scheduling intent from natural language (e.g., "book 15min with bailey"): ```bash theme={null} curl -X POST "https://api.cal.com/v2/bookings" \ -H "Content-Type: application/json" \ -H "cal-api-version: 2024-08-13" \ -d '{ "eventTypeSlug": "15min", "username": "bailey", "start": "2024-01-15T09:00:00Z", "attendee": { "name": "John Doe", "email": "john@example.com", "timeZone": "America/New_York" } }' ``` The booking creation endpoint is public and does not require authentication. This allows agents to book on behalf of external users. ### 3. Handle custom booking questions Most Cal.com users have required questions on their booking pages (e.g., "What is this meeting about?"). If you omit required fields, the API returns a 400 error. Include responses in `bookingFieldsResponses`: ```bash theme={null} curl -X POST "https://api.cal.com/v2/bookings" \ -H "Content-Type: application/json" \ -H "cal-api-version: 2024-08-13" \ -d '{ "eventTypeSlug": "consultation", "username": "bailey", "start": "2024-01-15T09:00:00Z", "attendee": { "name": "John Doe", "email": "john@example.com", "timeZone": "America/New_York" }, "bookingFieldsResponses": { "notes": "Discussing the new AI integration", "company_size": "10-50" } }' ``` To discover which fields are required, fetch the event type details first. The `bookingFields` array shows all custom questions and their requirements. ### 4. Instant bookings for urgent requests For teams handling urgent requests, use the `instant` flag to bypass normal scheduling and immediately ring available team members: ```bash theme={null} curl -X POST "https://api.cal.com/v2/bookings" \ -H "Content-Type: application/json" \ -H "cal-api-version: 2024-08-13" \ -d '{ "eventTypeSlug": "urgent-support", "username": "support-team", "start": "2024-01-15T09:00:00Z", "instant": true, "attendee": { "name": "John Doe", "email": "john@example.com", "timeZone": "America/New_York" } }' ``` Instant bookings require the event type to be configured for instant meetings. This is ideal for AI agents routing urgent customer requests. ### 5. Get user's event types Retrieve available event types to offer booking options: ```bash theme={null} curl -X GET "https://api.cal.com/v2/event-types?username=bailey" \ -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \ -H "cal-api-version: 2024-08-13" ``` ### 6. Reschedule a booking Move an existing booking to a new time: ```bash theme={null} curl -X POST "https://api.cal.com/v2/bookings/{bookingUid}/reschedule" \ -H "Content-Type: application/json" \ -H "cal-api-version: 2024-08-13" \ -d '{ "start": "2024-01-16T10:00:00Z", "rescheduleReason": "Attendee requested different time" }' ``` ### 7. Cancel a booking ```bash theme={null} curl -X POST "https://api.cal.com/v2/bookings/{bookingUid}/cancel" \ -H "Content-Type: application/json" \ -H "cal-api-version: 2024-08-13" \ -d '{ "cancellationReason": "Meeting no longer needed" }' ``` ## Credit management If your AI agent runs on the Cal.com platform, you can track usage by checking and charging credits through the API. This is useful for metering agent interactions against your account's credit balance. ### Check available credits Before performing a billable action, verify that the user or team has sufficient credits: ```bash theme={null} curl -X GET "https://api.cal.com/v2/credits/available" \ -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \ -H "cal-api-version: 2024-08-13" ``` Response: ```json theme={null} { "status": "success", "data": { "hasCredits": true, "balance": { "monthlyRemaining": 450, "additional": 200 } } } ``` The `balance` object breaks down your remaining credits: * `monthlyRemaining` — credits included in your current billing cycle * `additional` — purchased credits outside the monthly allowance ### Charge credits After a completed agent interaction, charge the appropriate number of credits: ```bash theme={null} curl -X POST "https://api.cal.com/v2/credits/charge" \ -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "cal-api-version: 2024-08-13" \ -d '{ "credits": 5, "creditFor": "AI_AGENT", "externalRef": "agent-thread-abc-1711432800000" }' ``` Response: ```json theme={null} { "status": "success", "data": { "charged": true, "remainingBalance": { "monthlyRemaining": 445, "additional": 200 } } } ``` | Parameter | Required | Description | | ------------- | -------- | ------------------------------------------------------------------------------------------------- | | `credits` | Yes | Number of credits to charge (minimum 1) | | `creditFor` | Yes | Usage type — use `AI_AGENT` for agent interactions | | `externalRef` | No | Unique reference string for idempotency. Prevents double-charging if the same request is retried. | Always include an `externalRef` tied to your agent's conversation or thread ID. This prevents duplicate charges if a network retry sends the same request twice. ### Example: check-then-charge pattern ```typescript theme={null} const headers = { "Authorization": "Bearer cal_live_xxxxxxxxxxxx", "Content-Type": "application/json", "cal-api-version": "2024-08-13" }; // 1. Check credits before starting work const available = await fetch("https://api.cal.com/v2/credits/available", { headers }); const { data } = await available.json(); if (!data.hasCredits) { throw new Error("No credits available"); } // 2. Perform the agent interaction const result = await runAgentTask(); // 3. Charge credits after completion await fetch("https://api.cal.com/v2/credits/charge", { method: "POST", headers, body: JSON.stringify({ credits: 5, creditFor: "AI_AGENT", externalRef: `thread-${threadId}-${Date.now()}` }) }); ``` ## Best practices for AI agents ### Handle time zones correctly Always specify time zones explicitly. Store user preferences and pass them in requests: ```json theme={null} { "attendee": { "timeZone": "Europe/London" } } ``` ### Implement retry logic API requests may occasionally fail. Implement exponential backoff: ```typescript theme={null} async function callWithRetry(fn: () => Promise, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { const response = await fn(); if (response.ok) return response; if (response.status === 429) { await sleep(Math.pow(2, i) * 1000); continue; } throw new Error(`API error: ${response.status}`); } catch (error) { if (i === maxRetries - 1) throw error; await sleep(Math.pow(2, i) * 1000); } } } ``` ### Validate availability before booking Always check slots before attempting to create a booking to avoid conflicts: ```typescript theme={null} // 1. Get available slots const slots = await getAvailableSlots("bailey", "15min", startDate, endDate); // 2. Verify the desired slot is available const isAvailable = slots.some(slot => slot.time === desiredTime); // 3. Create booking only if slot is available if (isAvailable) { await createBooking("bailey", "15min", desiredTime, attendee); } ``` ### Use webhooks for real-time updates Configure webhooks to receive notifications when bookings are created, rescheduled, or cancelled: ```bash theme={null} curl -X POST "https://api.cal.com/v2/webhooks" \ -H "Authorization: Bearer cal_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "cal-api-version: 2024-08-13" \ -d '{ "subscriberUrl": "https://your-agent.com/webhooks/cal", "eventTriggers": ["BOOKING_CREATED", "BOOKING_RESCHEDULED", "BOOKING_CANCELLED"], "active": true }' ``` ## Rate limits API key authentication allows **120 requests per minute** by default. Contact support if you need higher limits for production agents. ## API reference For complete endpoint documentation, see the [API v2 Reference](/docs/api-reference/v2/introduction). Key endpoints for agents: | Endpoint | Description | | ----------------------------------- | -------------------------- | | `GET /v2/slots` | Check available time slots | | `POST /v2/bookings` | Create a new booking | | `POST /v2/bookings/:uid/reschedule` | Reschedule a booking | | `POST /v2/bookings/:uid/cancel` | Cancel a booking | | `GET /v2/event-types` | List event types | | `GET /v2/schedules` | Get user schedules | | `POST /v2/webhooks` | Configure webhooks | | `GET /v2/credits/available` | Check credit balance | | `POST /v2/credits/charge` | Charge credits for usage | # Access Control Source: https://cal.com/docs/api-reference/v2/access-control Roles, permissions, and OAuth scopes for organizations and teams API v2 endpoints Organization and team API endpoints can use one of the three layers of access control: **roles**, **PBAC (Permission-Based Access Control)**, and **OAuth access token scopes**. Roles are the default mechanism — every organization and team endpoint requires a minimum membership role, for example authenticated user must have a team admin membership to access certain endpoints. PBAC is an opt-in feature that adds fine-grained permissions on top. OAuth scopes determine which endpoints an OAuth access token can reach. ## Roles Every organization and team endpoint requires the authenticated user to have a membership with a minimum role. There are three roles, from highest to lowest privilege: | Level | Roles (highest to lowest) | | ------------ | ---------------------------- | | Organization | `owner` > `admin` > `member` | | Team | `owner` > `admin` > `member` | ### Role hierarchy Higher roles can access endpoints that require a lower role. For example, if an endpoint requires `admin`, a user with the `owner` role can also access it. ### Organization roles grant team access Organization-level roles carry over to team endpoints: * **Org `admin` or `owner`** can access any team endpoint, regardless of team membership or the required team role. Organization level is above team level in terms of permissions. * **Org `member`** must have a separate team membership. Their team role is then checked against the required team role. For example, if a team endpoint requires `team admin`: * A user with `org admin` or `org owner` membership can access it directly — no team membership needed. * A user with `org member` membership needs a `team admin` (or `team owner`) membership in that specific team. ### Managing memberships Use these endpoints to manage organization and team memberships: **Organization memberships** | Method | Endpoint | | -------- | ------------------------------------------------------------------------------------------------------------- | | `POST` | [/v2/organizations//memberships](https://cal.com/docs/api-reference/v2/orgs-memberships/create-a-membership) | | `GET` | [/v2/organizations//memberships](https://cal.com/docs/api-reference/v2/orgs-memberships/get-all-memberships) | | `GET` | [/v2/organizations//memberships/](https://cal.com/docs/api-reference/v2/orgs-memberships/get-a-membership) | | `PATCH` | [/v2/organizations//memberships/](https://cal.com/docs/api-reference/v2/orgs-memberships/update-a-membership) | | `DELETE` | [/v2/organizations//memberships/](https://cal.com/docs/api-reference/v2/orgs-memberships/delete-a-membership) | **Team memberships** | Method | Endpoint | | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `POST` | [/v2/organizations//teams//memberships](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/create-a-membership) | | `GET` | [/v2/organizations//teams//memberships](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/get-all-memberships) | | `GET` | [/v2/organizations//teams//memberships/](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/get-a-membership) | | `PATCH` | [/v2/organizations//teams//memberships/](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/update-a-membership) | | `DELETE` | [/v2/organizations//teams//memberships/](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/delete-a-membership) | ## PBAC (Permission-Based Access Control) PBAC is an opt-in feature enabled per organization. It lets you define custom roles with specific permissions for organization members. Instead of relying solely on admin/member roles, you can create granular roles like "Booking Manager" or "Team Lead" that have access to only the endpoints they need. ### How it works Each endpoint has both a required membership role and a PBAC permission (e.g. `eventType.update`). Access is determined as follows: 1. **PBAC is not enabled** — the system checks if the authenticated user has a membership with the required role (e.g. `org admin`). Users with a higher role (e.g. `org owner`) can also access endpoints that require a lower role. 2. **PBAC is enabled and user has the required permission** — access is granted and the membership role check is skipped. 3. **PBAC is enabled but user is missing the permission** — falls back to the membership role check in step 1. ### Setting up PBAC 1. **Create a custom role** with specific permissions using the [Roles API](#managing-roles-and-permissions) 2. **Assign the role** to an organization or team membership 3. When the member makes API requests, PBAC checks if their role includes the required permission for that endpoint ### Managing roles and permissions Use the following endpoints to create roles, assign permissions, and manage access for your organization members. #### Roles | Method | Endpoint | | -------- | -------------------------------------------------------------------------------------------------------------- | | `POST` | [/v2/organizations//roles](https://cal.com/docs/api-reference/v2/orgs-roles/create-a-new-organization-role) | | `GET` | [/v2/organizations//roles](https://cal.com/docs/api-reference/v2/orgs-roles/get-all-organization-roles) | | `GET` | [/v2/organizations//roles/](https://cal.com/docs/api-reference/v2/orgs-roles/get-a-specific-organization-role) | | `PATCH` | [/v2/organizations//roles/](https://cal.com/docs/api-reference/v2/orgs-roles/update-an-organization-role) | | `DELETE` | [/v2/organizations//roles/](https://cal.com/docs/api-reference/v2/orgs-roles/delete-an-organization-role) | #### Role permissions | Method | Endpoint | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | [/v2/organizations//roles//permissions](https://cal.com/docs/api-reference/v2/orgs-roles-permissions/add-permissions-to-an-organization-role-single-or-batch) | | `GET` | [/v2/organizations//roles//permissions](https://cal.com/docs/api-reference/v2/orgs-roles-permissions/list-permissions-for-an-organization-role) | | `PUT` | [/v2/organizations//roles//permissions](https://cal.com/docs/api-reference/v2/orgs-roles-permissions/replace-all-permissions-for-an-organization-role) | | `DELETE` | [/v2/organizations//roles//permissions/](https://cal.com/docs/api-reference/v2/orgs-roles-permissions/remove-a-permission-from-an-organization-role) | | `DELETE` | [/v2/organizations//roles//permissions](https://cal.com/docs/api-reference/v2/orgs-roles-permissions/remove-multiple-permissions-from-an-organization-role) | ### Endpoint descriptions Each organization and team endpoint description mentions the minimum membership role and PBAC permission required to access it. ## OAuth Access Token Scopes When accessing the API using an **OAuth access token**, the scopes granted during the authorization flow determine which endpoints the token can call. Any request to an endpoint outside the granted scopes will be rejected. ### How it works 1. When creating an OAuth client, you select the scopes your application needs. 2. During the authorization flow, the user sees which scopes your application is requesting and grants access. 3. The issued access token can only call endpoints covered by the granted scopes. ### How to tell if an endpoint supports OAuth If an endpoint description mentions a specific OAuth access token scope (e.g. *"If accessed using an OAuth access token, the `BOOKING_READ` scope is required"*), you can access it using an OAuth access token with that scope. If no OAuth scope is mentioned in the endpoint description, the endpoint is not accessible using an OAuth access token. ### Scope levels Scopes are organized into three levels: | Level | Prefix | Example | Description | | ------------ | -------- | ------------------- | ----------------------------------------------- | | Individual | *(none)* | `BOOKING_READ` | Access the authenticated user's own resources | | Team | `TEAM_` | `TEAM_BOOKING_READ` | Access resources belonging to a specific team | | Organization | `ORG_` | `ORG_BOOKING_READ` | Access resources across the entire organization | An `ORG_` scope automatically grants the corresponding `TEAM_` scope. For example, a token with `ORG_PROFILE_READ` can also access endpoints that require `TEAM_PROFILE_READ`. For a full list of available scopes and the endpoints they cover, see [OAuth — Available Scopes](https://cal.com/docs/api-reference/v2/oauth#available-scopes). # Refresh API Key Source: https://cal.com/docs/api-reference/v2/api-keys/refresh-api-key /api-reference/v2/openapi.json post /v2/api-keys/refresh Generate a new API key and delete the current one. Provide API key to refresh as a Bearer token in the Authorization header (e.g. "Authorization: Bearer "). # Add an attendee to a booking Source: https://cal.com/docs/api-reference/v2/bookings-attendees/add-an-attendee-to-a-booking /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/attendees Add a new attendee to an existing booking by its UID. **Side effects:** - The booking's attendee list is updated in the database - The calendar event is updated on connected calendars (Google Calendar, Outlook, etc.) to include the new attendee - An email notification is sent to the new attendee with the booking details **Permissions:** - The authenticated user must be either the booking organizer, an existing attendee, or have the `booking.update` permission for the team The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Get a specific attendee for a booking Source: https://cal.com/docs/api-reference/v2/bookings-attendees/get-a-specific-attendee-for-a-booking /api-reference/v2/openapi.json get /v2/bookings/{bookingUid}/attendees/{attendeeId} Retrieve a specific attendee by their ID for a booking identified by its UID. The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error. If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Get all attendees for a booking Source: https://cal.com/docs/api-reference/v2/bookings-attendees/get-all-attendees-for-a-booking /api-reference/v2/openapi.json get /v2/bookings/{bookingUid}/attendees Retrieve all attendees for a specific booking by its UID. The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error. If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Add guests to an existing booking Source: https://cal.com/docs/api-reference/v2/bookings-guests/add-guests-to-an-existing-booking /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/guests Add one or more guests to an existing booking. Maximum 10 guests per request, with a limit of 30 total guests per booking. **Rate Limiting:** This endpoint is rate limited to 5 requests per minute to prevent abuse. **Email Notifications:** When guests are added, the following notifications are sent (unless disabled by event type settings): - **Organizer & Team Members:** Receive an "Add Guests" notification email informing them that new guests have been added to the booking. - **New Guests:** Receive a "Scheduled Event" email with full booking details and calendar invite. If they have a phone number, they also receive an SMS notification. - **Existing Guests:** Receive an "Add Guests" notification email informing them that additional guests have been added to the booking. The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Cancel a booking Source: https://cal.com/docs/api-reference/v2/bookings/cancel-a-booking /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/cancel :bookingUid can be :bookingUid of an usual booking, individual recurrence or recurring booking to cancel all recurrences. Cancelling normal bookings: If the booking is not seated and not recurring, simply pass :bookingUid in the request URL `/bookings/:bookingUid/cancel` and optionally cancellationReason in the request body `{"cancellationReason": "Will travel"}`. Cancelling seated bookings: It is possible to cancel specific seat within a booking as an attendee or all of the seats as the host. 1. As an attendee - provide :bookingUid in the request URL `/bookings/:bookingUid/cancel` and seatUid in the request body `{"seatUid": "123-123-123"}` . This will remove this particular attendance from the booking. 2. As the host or org admin of host - host can cancel booking for all attendees aka for every seat, this also applies to org admins. Provide :bookingUid in the request URL `/bookings/:bookingUid/cancel` and cancellationReason in the request body `{"cancellationReason": "Will travel"}` and `Authorization: Bearer token` request header where token is event type owner (host) credential. This will cancel the booking for all attendees. Cancelling recurring seated bookings: For recurring seated bookings it is not possible to cancel all of them with 1 call like with non-seated recurring bookings by providing recurring bookind uid - you have to cancel each recurrence booking by its bookingUid + seatUid. If you are cancelling a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. # Confirm a booking Source: https://cal.com/docs/api-reference/v2/bookings/confirm-a-booking /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/confirm The provided authorization header refers to the owner of the booking. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Create a booking Source: https://cal.com/docs/api-reference/v2/bookings/create-a-booking /api-reference/v2/openapi.json post /v2/bookings POST /v2/bookings is used to create regular bookings, recurring bookings and instant bookings. The request bodies for all 3 are almost the same except: If eventTypeId in the request body is id of a regular event, then regular booking is created. If it is an id of a recurring event type, then recurring booking is created. Meaning that the request bodies are equal but the outcome depends on what kind of event type it is with the goal of making it as seamless for developers as possible. For team event types it is possible to create instant meeting. To do that just pass `"instant": true` to the request body. The start needs to be in UTC aka if the timezone is GMT+2 in Rome and meeting should start at 11, then UTC time should have hours 09:00 aka without time zone. Finally, there are 2 ways to book an event type belonging to an individual user: 1. Provide `eventTypeId` in the request body. 2. Provide `eventTypeSlug` and `username` and optionally `organizationSlug` if the user with the username is within an organization. And 2 ways to book and event type belonging to a team: 1. Provide `eventTypeId` in the request body. 2. Provide `eventTypeSlug` and `teamSlug` and optionally `organizationSlug` if the team with the teamSlug is within an organization. If you are creating a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner. For event types that have SMS reminders workflow, you need to pass the attendee's phone number in the request body via `attendee.phoneNumber` (e.g., "+19876543210" in international format). This is an optional field, but becomes required when SMS reminders are enabled for the event type. For the complete attendee object structure, see the [attendee object](https://cal.com/docs/api-reference/v2/bookings/create-a-booking#body-attendee) documentation. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. # Decline a booking Source: https://cal.com/docs/api-reference/v2/bookings/decline-a-booking /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/decline The provided authorization header refers to the owner of the booking. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Get a booking Source: https://cal.com/docs/api-reference/v2/bookings/get-a-booking /api-reference/v2/openapi.json get /v2/bookings/{bookingUid} `:bookingUid` can be 1. uid of a normal booking 2. uid of one of the recurring booking recurrences 3. uid of recurring booking which will return an array of all recurring booking recurrences (stored as recurringBookingUid on one of the individual recurrences). If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. # Get a booking by seat UID Source: https://cal.com/docs/api-reference/v2/bookings/get-a-booking-by-seat-uid /api-reference/v2/openapi.json get /v2/bookings/by-seat/{seatUid} Get a seated booking by its seat reference UID. This is useful when you have a seatUid from a seated booking and want to retrieve the full booking details. If you are fetching a seated booking for an event type with 'show attendees' disabled, then to retrieve attendees in the response either set 'show attendees' to true on event type level or you have to provide an authentication method of event type owner, host, team admin or owner or org admin or owner. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. # Get 'Add to Calendar' links for a booking Source: https://cal.com/docs/api-reference/v2/bookings/get-add-to-calendar-links-for-a-booking /api-reference/v2/openapi.json get /v2/bookings/{bookingUid}/calendar-links Retrieve calendar links for a booking that can be used to add the event to various calendar services. Returns links for Google Calendar, Microsoft Office, Microsoft Outlook, and a downloadable ICS file. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Get all bookings Source: https://cal.com/docs/api-reference/v2/bookings/get-all-bookings /api-reference/v2/openapi.json get /v2/bookings Cursor-based pagination. Pass the `pagination.nextCursor` from the previous response as the `cursor` query parameter to fetch the next page. Omit `cursor` to fetch the first page. `pagination.hasMore` is `false` and `pagination.nextCursor` is `null` when you've reached the last page. Must pass `cal-api-version: 2026-05-01` header. **`status` filters to a single status.** Pass one (e.g. `?status=upcoming`) or omit to walk all statuses. To list bookings across multiple statuses, issue parallel requests — one per status — and merge client-side. The sort direction and the page-1 anchor are derived from `status`: | `status` | Sort | Walk direction | Page-1 anchor (uuid bound) | |---|---|---|---| | _(omitted)_ | `Booking.uuid DESC` | Backward from far-future | upper bound at year 2100 | | `upcoming` | `Booking.uuid ASC` | Forward in time | lower bound at `NOW() − 1h` | | `recurring` | `Booking.uuid ASC` | Forward in time | lower bound at `NOW() − 1h` | | `unconfirmed` | `Booking.uuid ASC` | Forward in time | lower bound at `NOW() − 1h` | | `past` | `Booking.uuid DESC` | Backward in time | upper bound at `NOW()` | | `cancelled` | `Booking.uuid DESC` | Backward from far-future | upper bound at year 2100 | If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Get all the recordings for the booking Source: https://cal.com/docs/api-reference/v2/bookings/get-all-the-recordings-for-the-booking /api-reference/v2/openapi.json get /v2/bookings/{bookingUid}/recordings Fetches all the recordings for the booking `:bookingUid`. Requires authentication and proper authorization. Access is granted if you are the booking organizer, team admin or org admin/owner. cal-api-version: `2026-02-25` is required in the request header. If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Get booking references Source: https://cal.com/docs/api-reference/v2/bookings/get-booking-references /api-reference/v2/openapi.json get /v2/bookings/{bookingUid}/references Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Get Cal Video real time transcript download links for the booking Source: https://cal.com/docs/api-reference/v2/bookings/get-cal-video-real-time-transcript-download-links-for-the-booking /api-reference/v2/openapi.json get /v2/bookings/{bookingUid}/transcripts Fetches all the transcript download links for the booking `:bookingUid` Transcripts are generated when clicking "Transcribe" during a Cal Video meeting. Download links are valid for 1 hour only - make a new request to generate fresh links after expiration. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Get Video Meeting Sessions. Only supported for Cal Video Source: https://cal.com/docs/api-reference/v2/bookings/get-video-meeting-sessions-only-supported-for-cal-video /api-reference/v2/openapi.json get /v2/bookings/{bookingUid}/conferencing-sessions Requires authentication and proper authorization. Access is granted if you are the booking organizer, team admin or org admin/owner. cal-api-version: `2026-02-25` is required in the request header. This endpoint is rate-limited to 60 requests per minute per caller (per API key, access token, OAuth client, or IP). Exceeding the limit returns a 429 response and blocks further calls for 60 seconds. If the upstream conferencing provider rate-limits the request, this endpoint responds with HTTP 429 and a `Retry-After` header carrying the number of seconds to wait before retrying. Clients should honor this hint. If accessed using an OAuth access token, the `BOOKING_READ` scope is required. # Mark a booking absence Source: https://cal.com/docs/api-reference/v2/bookings/mark-a-booking-absence /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/mark-absent The provided authorization header refers to the owner of the booking. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Reassign a booking to a specific host Source: https://cal.com/docs/api-reference/v2/bookings/reassign-a-booking-to-a-specific-host /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/reassign/{userId} Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Reassign a booking to auto-selected host Source: https://cal.com/docs/api-reference/v2/bookings/reassign-a-booking-to-auto-selected-host /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/reassign Currently only supports reassigning host for round robin bookings. The provided authorization header refers to the owner of the booking. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Request to reschedule a booking Source: https://cal.com/docs/api-reference/v2/bookings/request-to-reschedule-a-booking /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/request-reschedule Request to reschedule a booking. The booking will be cancelled and the attendee will receive an email with a link to reschedule. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Reschedule a booking Source: https://cal.com/docs/api-reference/v2/bookings/reschedule-a-booking /api-reference/v2/openapi.json post /v2/bookings/{bookingUid}/reschedule Reschedule a booking or seated booking. Reschedulable booking statuses: - `accepted` — the confirmed booking is moved to the new start time. - `pending` — a booking awaiting host confirmation can be rescheduled. The new booking stays `pending` until the host confirms or declines it. Non-reschedulable booking statuses (endpoint responds with `400 Bad Request`): - `cancelled` — the booking has already been cancelled. If it was cancelled because it was previously rescheduled, the error message includes the UID of the booking it was rescheduled to. - `rejected` — the host declined the original confirmation-required request. Create a new booking instead. - `awaiting_host` — an instant meeting that is live and waiting for a host to join. Create a new booking instead. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. # Update booking location for an existing booking Source: https://cal.com/docs/api-reference/v2/bookings/update-booking-location-for-an-existing-booking /api-reference/v2/openapi.json patch /v2/bookings/{bookingUid}/location Updates the booking location in Cal.com. For integration locations (e.g. Zoom, Google Meet, Cal Video), the endpoint also provisions a conference link and updates the corresponding calendar event via the organizer's connected credentials. The cal-api-version header is required for this endpoint. Without it, the request will fail with a 404 error. If accessed using an OAuth access token, the `BOOKING_WRITE` scope is required. # Get meeting details from calendar Source: https://cal.com/docs/api-reference/v2/cal-unified-calendars/get-meeting-details-from-calendar /api-reference/v2/openapi.json get /v2/calendars/{calendar}/event/{eventUid} Returns detailed information about a meeting including attendance metrics. If accessed using an OAuth access token, the `APPS_READ` scope is required. # Update meeting details in calendar Source: https://cal.com/docs/api-reference/v2/cal-unified-calendars/update-meeting-details-in-calendar /api-reference/v2/openapi.json patch /v2/calendars/{calendar}/events/{eventUid} Updates event information in the specified calendar provider. If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Check a calendar connection Source: https://cal.com/docs/api-reference/v2/calendars/check-a-calendar-connection /api-reference/v2/openapi.json get /v2/calendars/{calendar}/check If accessed using an OAuth access token, the `APPS_READ` scope is required. # Check an ICS feed Source: https://cal.com/docs/api-reference/v2/calendars/check-an-ics-feed /api-reference/v2/openapi.json get /v2/calendars/ics-feed/check If accessed using an OAuth access token, the `APPS_READ` scope is required. # Disconnect a calendar Source: https://cal.com/docs/api-reference/v2/calendars/disconnect-a-calendar /api-reference/v2/openapi.json post /v2/calendars/{calendar}/disconnect If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Get all calendars Source: https://cal.com/docs/api-reference/v2/calendars/get-all-calendars /api-reference/v2/openapi.json get /v2/calendars If accessed using an OAuth access token, the `APPS_READ` scope is required. # Get busy times Source: https://cal.com/docs/api-reference/v2/calendars/get-busy-times /api-reference/v2/openapi.json get /v2/calendars/busy-times Get busy times from a calendar. Example request URL is `https://api.cal.com/v2/calendars/busy-times?timeZone=Europe%2FMadrid&dateFrom=2024-12-18&dateTo=2024-12-18&calendarsToLoad[0][credentialId]=135&calendarsToLoad[0][externalId]=skrauciz%40gmail.com`. Note: loggedInUsersTz is deprecated, use timeZone instead. If accessed using an OAuth access token, the `APPS_READ` scope is required. # Get OAuth connect URL Source: https://cal.com/docs/api-reference/v2/calendars/get-oauth-connect-url /api-reference/v2/openapi.json get /v2/calendars/{calendar}/connect If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Save an ICS feed Source: https://cal.com/docs/api-reference/v2/calendars/save-an-ics-feed /api-reference/v2/openapi.json post /v2/calendars/ics-feed/save If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Save Apple calendar credentials Source: https://cal.com/docs/api-reference/v2/calendars/save-apple-calendar-credentials /api-reference/v2/openapi.json post /v2/calendars/{calendar}/credentials If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Save Google or Outlook calendar credentials Source: https://cal.com/docs/api-reference/v2/calendars/save-google-or-outlook-calendar-credentials /api-reference/v2/openapi.json get /v2/calendars/{calendar}/save # Conferencing app OAuth callback Source: https://cal.com/docs/api-reference/v2/conferencing/conferencing-app-oauth-callback /api-reference/v2/openapi.json get /v2/conferencing/{app}/oauth/callback # Connect your conferencing application Source: https://cal.com/docs/api-reference/v2/conferencing/connect-your-conferencing-application /api-reference/v2/openapi.json post /v2/conferencing/{app}/connect If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Disconnect your conferencing application Source: https://cal.com/docs/api-reference/v2/conferencing/disconnect-your-conferencing-application /api-reference/v2/openapi.json delete /v2/conferencing/{app}/disconnect If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Get OAuth conferencing app auth URL Source: https://cal.com/docs/api-reference/v2/conferencing/get-oauth-conferencing-app-auth-url /api-reference/v2/openapi.json get /v2/conferencing/{app}/oauth/auth-url If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Get your default conferencing application Source: https://cal.com/docs/api-reference/v2/conferencing/get-your-default-conferencing-application /api-reference/v2/openapi.json get /v2/conferencing/default If accessed using an OAuth access token, the `APPS_READ` scope is required. # List your conferencing applications Source: https://cal.com/docs/api-reference/v2/conferencing/list-your-conferencing-applications /api-reference/v2/openapi.json get /v2/conferencing If accessed using an OAuth access token, the `APPS_READ` scope is required. # Set your default conferencing application Source: https://cal.com/docs/api-reference/v2/conferencing/set-your-default-conferencing-application /api-reference/v2/openapi.json post /v2/conferencing/{app}/default If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Charge credits Source: https://cal.com/docs/api-reference/v2/credits/charge-credits /api-reference/v2/openapi.json post /v2/credits/charge Charge credits for an authenticated user. Uses externalRef for idempotency to prevent double-charging. Third-party OAuth tokens require the `CREDITS_WRITE` scope. # Check available credits Source: https://cal.com/docs/api-reference/v2/credits/check-available-credits /api-reference/v2/openapi.json get /v2/credits/available Check if the authenticated user (or their org/team) has available credits and return the current balance. Third-party OAuth tokens require the `CREDITS_READ` scope. # Create a managed user Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/create-a-managed-user /api-reference/v2/openapi.json post /v2/oauth-clients/{clientId}/users These endpoints are deprecated and will be removed in the future. # Delete a managed user Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/delete-a-managed-user /api-reference/v2/openapi.json delete /v2/oauth-clients/{clientId}/users/{userId} These endpoints are deprecated and will be removed in the future. # Force refresh tokens Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/force-refresh-tokens /api-reference/v2/openapi.json post /v2/oauth-clients/{clientId}/users/{userId}/force-refresh These endpoints are deprecated and will be removed in the future. If you have lost managed user access or refresh token, then you can get new ones by using OAuth credentials. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields. Response also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields. # Get a managed user Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/get-a-managed-user /api-reference/v2/openapi.json get /v2/oauth-clients/{clientId}/users/{userId} These endpoints are deprecated and will be removed in the future. # Get all managed users Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/get-all-managed-users /api-reference/v2/openapi.json get /v2/oauth-clients/{clientId}/users These endpoints are deprecated and will be removed in the future. # Refresh managed user tokens Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/refresh-managed-user-tokens /api-reference/v2/openapi.json post /v2/oauth/{clientId}/refresh These endpoints are deprecated and will be removed in the future. If managed user access token is expired then get a new one using this endpoint - it will also refresh the refresh token, because we use "refresh token rotation" mechanism. Access token is valid for 60 minutes and refresh token for 1 year. Make sure to store them in your database, for example, in your User database model `calAccessToken` and `calRefreshToken` fields. Response also contains `accessTokenExpiresAt` and `refreshTokenExpiresAt` fields, but if you decode the jwt token the payload will contain `clientId` (OAuth client ID), `ownerId` (user to whom token belongs ID), `iat` (issued at time) and `expiresAt` (when does the token expire) fields. # Update a managed user Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-managed-users/update-a-managed-user /api-reference/v2/openapi.json patch /v2/oauth-clients/{clientId}/users/{userId} These endpoints are deprecated and will be removed in the future. # Create an OAuth client Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/create-an-oauth-client /api-reference/v2/openapi.json post /v2/oauth-clients These endpoints are deprecated and will be removed in the future. # Delete an OAuth client Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/delete-an-oauth-client /api-reference/v2/openapi.json delete /v2/oauth-clients/{clientId} These endpoints are deprecated and will be removed in the future. # Get all OAuth clients Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/get-all-oauth-clients /api-reference/v2/openapi.json get /v2/oauth-clients These endpoints are deprecated and will be removed in the future. # Get an OAuth client Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/get-an-oauth-client /api-reference/v2/openapi.json get /v2/oauth-clients/{clientId} These endpoints are deprecated and will be removed in the future. # Update an OAuth client Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-oauth-clients/update-an-oauth-client /api-reference/v2/openapi.json patch /v2/oauth-clients/{clientId} These endpoints are deprecated and will be removed in the future. # Create a webhook Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/create-a-webhook /api-reference/v2/openapi.json post /v2/oauth-clients/{clientId}/webhooks These endpoints are deprecated and will be removed in the future. # Delete a webhook Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/delete-a-webhook /api-reference/v2/openapi.json delete /v2/oauth-clients/{clientId}/webhooks/{webhookId} These endpoints are deprecated and will be removed in the future. # Delete all webhooks Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/delete-all-webhooks /api-reference/v2/openapi.json delete /v2/oauth-clients/{clientId}/webhooks These endpoints are deprecated and will be removed in the future. # Get a webhook Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/get-a-webhook /api-reference/v2/openapi.json get /v2/oauth-clients/{clientId}/webhooks/{webhookId} These endpoints are deprecated and will be removed in the future. # Get all webhooks Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/get-all-webhooks /api-reference/v2/openapi.json get /v2/oauth-clients/{clientId}/webhooks These endpoints are deprecated and will be removed in the future. # Update a webhook Source: https://cal.com/docs/api-reference/v2/deprecated:-platform-webhooks/update-a-webhook /api-reference/v2/openapi.json patch /v2/oauth-clients/{clientId}/webhooks/{webhookId} These endpoints are deprecated and will be removed in the future. # Update destination calendars Source: https://cal.com/docs/api-reference/v2/destination-calendars/update-destination-calendars /api-reference/v2/openapi.json put /v2/destination-calendars If accessed using an OAuth access token, the `APPS_WRITE` scope is required. # Create a private link for an event type Source: https://cal.com/docs/api-reference/v2/event-types-private-links/create-a-private-link-for-an-event-type /api-reference/v2/openapi.json post /v2/event-types/{eventTypeId}/private-links If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Delete a private link for an event type Source: https://cal.com/docs/api-reference/v2/event-types-private-links/delete-a-private-link-for-an-event-type /api-reference/v2/openapi.json delete /v2/event-types/{eventTypeId}/private-links/{linkId} If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Get all private links for an event type Source: https://cal.com/docs/api-reference/v2/event-types-private-links/get-all-private-links-for-an-event-type /api-reference/v2/openapi.json get /v2/event-types/{eventTypeId}/private-links If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. # Update a private link for an event type Source: https://cal.com/docs/api-reference/v2/event-types-private-links/update-a-private-link-for-an-event-type /api-reference/v2/openapi.json patch /v2/event-types/{eventTypeId}/private-links/{linkId} If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Create a webhook Source: https://cal.com/docs/api-reference/v2/event-types-webhooks/create-a-webhook /api-reference/v2/openapi.json post /v2/event-types/{eventTypeId}/webhooks If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Delete a webhook Source: https://cal.com/docs/api-reference/v2/event-types-webhooks/delete-a-webhook /api-reference/v2/openapi.json delete /v2/event-types/{eventTypeId}/webhooks/{webhookId} If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Delete all webhooks Source: https://cal.com/docs/api-reference/v2/event-types-webhooks/delete-all-webhooks /api-reference/v2/openapi.json delete /v2/event-types/{eventTypeId}/webhooks If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Get a webhook Source: https://cal.com/docs/api-reference/v2/event-types-webhooks/get-a-webhook /api-reference/v2/openapi.json get /v2/event-types/{eventTypeId}/webhooks/{webhookId} If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. # Get all webhooks Source: https://cal.com/docs/api-reference/v2/event-types-webhooks/get-all-webhooks /api-reference/v2/openapi.json get /v2/event-types/{eventTypeId}/webhooks If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. # Update a webhook Source: https://cal.com/docs/api-reference/v2/event-types-webhooks/update-a-webhook /api-reference/v2/openapi.json patch /v2/event-types/{eventTypeId}/webhooks/{webhookId} If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Create an event type Source: https://cal.com/docs/api-reference/v2/event-types/create-an-event-type /api-reference/v2/openapi.json post /v2/event-types Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Delete an event type Source: https://cal.com/docs/api-reference/v2/event-types/delete-an-event-type /api-reference/v2/openapi.json delete /v2/event-types/{eventTypeId} Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Get all event types Source: https://cal.com/docs/api-reference/v2/event-types/get-all-event-types /api-reference/v2/openapi.json get /v2/event-types Hidden event types are returned only if authentication is provided and it belongs to the event type owner. Use the optional `sortCreatedAt` query parameter to order results by creation date (by ID). Accepts "asc" (oldest first) or "desc" (newest first). When not provided, no explicit ordering is applied. Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. # Get an event type Source: https://cal.com/docs/api-reference/v2/event-types/get-an-event-type /api-reference/v2/openapi.json get /v2/event-types/{eventTypeId} Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. Access control: This endpoint fetches an event type by ID and returns it only if the authenticated user is authorized. Authorization is granted to: - System admins - The event type owner - Hosts of the event type or users assigned to the event type - Team admins/owners of the team that owns the team event type - Organization admins/owners of the event type owner's organization - Organization admins/owners of the team's parent organization Note: Update and delete endpoints remain restricted to the event type owner only. If accessed using an OAuth access token, the `EVENT_TYPE_READ` scope is required. # Update an event type Source: https://cal.com/docs/api-reference/v2/event-types/update-an-event-type /api-reference/v2/openapi.json patch /v2/event-types/{eventTypeId} Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint. If accessed using an OAuth access token, the `EVENT_TYPE_WRITE` scope is required. # Introduction to API v2 Source: https://cal.com/docs/api-reference/v2/introduction Introduction to Cal.com API v2 endpoints ## Authentication The Cal.com API has 3 authentication methods: 1. OAuth 2. API key 3. Platform (Deprecated) ### 1. Create an OAuth client and "Continue with Cal.com" In order to be listed as an official partner and App in our App Store: cal.com/apps you need to create and get a verified OAuth client. You can request it here: [https://cal.com/docs/api-reference/v2/oauth](https://cal.com/docs/api-reference/v2/oauth). ### 2. API key While API keys can be created easily, bear in mind we almost always recommend using OAuth credentials, especially when building integrations or applications with Cal.com. You can view and manage your API keys in your settings page under the security tab in Cal.com. API Keys are under Settings > Security Test mode secret keys have the prefix `cal_` and live mode secret keys have the prefix `cal_live_`. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via the Authorization header. For example, the request would go something like: ``` 'Authorization': 'Bearer YOUR_API_KEY' ``` in your request header. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. ## Teams endpoints Teams customers have all the endpoints except the ones prefixed with "Platform" and "Orgs". ## Organizations endpoints Organizations customers have all the endpoints except the ones prefixed with "Platform" and "Teams" and "Orgs / Orgs" because children organizations are only allowed in the platform plan right now. ## Rate limits There are three authentication methods for the API, and each of them has the following rate limits: 1. API Key - 120 requests per minute. This can be increased to a reasonable amount, such as 200 requests per minute. If you require a higher rate limit, such as 800 requests per minute, it is possible, but it may involve extra charges. To request this, please contact support. If no authentication method is provided, the default rate limit is 120 requests per minute. ## Deprecated & Maintenance for existing users only As of 15th December 2025, we're currently undergoing a restructuring of our "Platform"-offering. Until further we continue to provide enterprise support for existing customers but no longer offer new signups for any "Platform" plan. ### 2. Platform OAuth client credentials You need to use OAuth credentials when: 1. Managing managed users [API reference](https://cal.com/docs/api-reference/v2/platform-managed-users/create-a-managed-user) 2. Creating OAuth client webhooks [API reference](https://cal.com/docs/api-reference/v2/platform-webhooks/create-a-webhook) 3. Refreshing tokens of a managed user [API reference](https://cal.com/docs/api-reference/v2/platform-managed-users/refresh-managed-user-tokens) 4. Teams related endpoints: Managing organization teams [API reference](https://cal.com/docs/api-reference/v2/orgs-teams/create-a-team), adding managed users as members to teams [API reference](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/create-a-membership), creating team event types [API reference](https://cal.com/docs/api-reference/v2/orgs-event-types/create-an-event-type). OAuth credentials can be accessed in the platform dashboard [https://app.cal.com/settings/platform](https://app.cal.com/settings/platform) after you have created an OAuth client. Each one has an ID and secret. You then need to pass them as request headers: 1. `x-cal-client-id` - ID of the OAuth client. 2. `x-cal-secret-key` - secret of the OAuth client. ### 3. Platform Managed user access token After you create a managed user you will receive its access and refresh tokens. The response also includes managed user's id, so we recommend you to add new properties to your users table calAccessToken, calRefreshToken and calManagedUserId to store this information. You need to use access token when managing managed user's: 1. Schedules [API reference](https://cal.com/docs/api-reference/v2/schedules/create-a-schedule) 2. Event types [API reference](https://cal.com/docs/api-reference/v2/event-types/create-an-event-type) 3. Bookings - some endpoints like creating a booking is public, but some like getting all managed user's bookings require managed user's access token [API reference](https://cal.com/docs/api-reference/v2/bookings/get-all-bookings) It is passed as an authorization bearer request header Authorization: Bearer \. Validity period: access tokens are valid for 60 minutes and refresh tokens for 1 year, and tokens can be refreshed using the refresh endpoint [API reference](https://cal.com/docs/api-reference/v2/oauth/post-v2oauth-refresh). After refreshing you will receive the new access and refresh tokens that you have to store in your database. Recovering tokens: if you ever lose managed user's access or refresh tokens, you can force refresh them using the OAuth client credentials and store them in your database [API reference](https://cal.com/docs/api-reference/v2/platform-managed-users/force-refresh-tokens). ## Platform endpoints Platform customers have the following endpoints available: 1. Endpoints prefixed with "Platform". 2. Endpoints with no prefix e.g "Bookings", "Event Types". 3. If you are at least on the ESSENTIALS plan, then all endpoints prefixed with "Orgs" except "Orgs / Attributes", "Orgs / Attributes / Options" and "Orgs / Teams / Routing forms / Responses". # Create an organization within an organization Source: https://cal.com/docs/api-reference/v2/managed-orgs/create-an-organization-within-an-organization /api-reference/v2/openapi.json post /v2/organizations/{orgId}/organizations For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.create`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control # Delete an organization within an organization Source: https://cal.com/docs/api-reference/v2/managed-orgs/delete-an-organization-within-an-organization /api-reference/v2/openapi.json delete /v2/organizations/{orgId}/organizations/{managedOrganizationId} For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.delete`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control # Get all organizations within an organization Source: https://cal.com/docs/api-reference/v2/managed-orgs/get-all-organizations-within-an-organization /api-reference/v2/openapi.json get /v2/organizations/{orgId}/organizations For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control # Get an organization within an organization Source: https://cal.com/docs/api-reference/v2/managed-orgs/get-an-organization-within-an-organization /api-reference/v2/openapi.json get /v2/organizations/{orgId}/organizations/{managedOrganizationId} For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.read`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control # Update an organization within an organization Source: https://cal.com/docs/api-reference/v2/managed-orgs/update-an-organization-within-an-organization /api-reference/v2/openapi.json patch /v2/organizations/{orgId}/organizations/{managedOrganizationId} For platform, the plan must be 'SCALE' or higher to access this endpoint. Required membership role: `org admin`. PBAC permission: `organization.update`. Learn more about API access control at https://cal.com/docs/api-reference/v2/access-control # Clear my booking limits Source: https://cal.com/docs/api-reference/v2/me/clear-my-booking-limits /api-reference/v2/openapi.json delete /v2/me/booking-limits Removes all of the authenticated user's global booking limits. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required. # Get my booking limits Source: https://cal.com/docs/api-reference/v2/me/get-my-booking-limits /api-reference/v2/openapi.json get /v2/me/booking-limits Returns the authenticated user's global booking limits. Unset bounds are returned as null. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_READ` scope is required. # Get my profile Source: https://cal.com/docs/api-reference/v2/me/get-my-profile /api-reference/v2/openapi.json get /v2/me If accessed using an OAuth access token, the `PROFILE_READ` scope is required. # Update my booking limits Source: https://cal.com/docs/api-reference/v2/me/update-my-booking-limits /api-reference/v2/openapi.json patch /v2/me/booking-limits Partially updates the authenticated user's global booking limits. Only fields present in the request body are changed; omit a field to leave it untouched, or set it to null to remove that limit. Only available to organization members — non-org accounts receive a 403. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required. # Update my profile Source: https://cal.com/docs/api-reference/v2/me/update-my-profile /api-reference/v2/openapi.json patch /v2/me Updates the authenticated user's profile. Email changes require verification and the primary email stays unchanged until verification completes, unless the new email is already a verified secondary email or the user is platform-managed. If accessed using an OAuth access token, the `PROFILE_WRITE` scope is required. # Register an app push subscription Source: https://cal.com/docs/api-reference/v2/notifications/register-an-app-push-subscription /api-reference/v2/openapi.json post /v2/notifications/subscriptions/app-push # Remove an app push subscription Source: https://cal.com/docs/api-reference/v2/notifications/remove-an-app-push-subscription /api-reference/v2/openapi.json delete /v2/notifications/subscriptions/app-push # OAuth Source: https://cal.com/docs/api-reference/v2/oauth Authorize apps with Cal.com accounts using OAuth