Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/calcom/cal.com/llms.txt

Use this file to discover all available pages before exploring further.

The Schedules API allows you to create, retrieve, update, and delete availability schedules that define when users can be booked.

​
API Version

Schedule endpoints require the cal-api-version header: 
cal-api-version: 2024-06-11

​
Authentication

All schedule endpoints require authentication:
  • API Key: Pass via Authorization: Bearer <api-key> header
  • Access Token: OAuth access token
Required permissions:
  • SCHEDULE_READ for GET operations
  • SCHEDULE_WRITE for POST, PATCH, DELETE operations

​
Overview

Schedules define when a user is available for bookings. Each user should have:
  1. Default Schedule: The primary availability schedule used when event types don’t specify a custom schedule
  2. Custom Schedules: Additional schedules that specific event types can reference

​
Create a Schedule

Create a new availability schedule. 
curl --request POST \
  --url https://api.cal.com/v2/schedules \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Default Schedule",
    "timeZone": "America/New_York",
    "isDefault": true,
    "availability": [
      {
        "days": [1, 2, 3, 4, 5],
        "startTime": "09:00",
        "endTime": "17:00"
      }
    ]
  }'

​
Request Body

​
name
string
required
Schedule name (e.g., “Default Schedule”, “Evening Hours”)
​
timeZone
string
required
IANA timezone (e.g., “America/New_York”, “Europe/London”)
​
isDefault
boolean
Whether this is the default schedule. Each user should have exactly one default schedule.
​
availability
array
required
Array of availability rules
​
overrides
array
Date-specific overrides

​
Response

​
status
string
Status of the response (“success”)
​
data
object
Schedule details

​
Get Default Schedule

Retrieve the authenticated user’s default schedule. 
curl --request GET \
  --url https://api.cal.com/v2/schedules/default \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

​
Response

Returns the default schedule object, or null if no default schedule exists.

​
Get a Schedule

Retrieve a specific schedule by ID. 
curl --request GET \
  --url https://api.cal.com/v2/schedules/{scheduleId} \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

​
Path Parameters

​
scheduleId
number
required
The ID of the schedule to retrieve

​
Get All Schedules

List all schedules for the authenticated user. 
curl --request GET \
  --url https://api.cal.com/v2/schedules \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

​
Response

{
  "status": "success",
  "data": [
    {
      "id": 123,
      "name": "Default Schedule",
      "timeZone": "America/New_York",
      "isDefault": true,
      "availability": [
        {
          "days": [1, 2, 3, 4, 5],
          "startTime": "09:00",
          "endTime": "17:00"
        }
      ]
    },
    {
      "id": 456,
      "name": "Evening Hours",
      "timeZone": "America/New_York",
      "isDefault": false,
      "availability": [
        {
          "days": [1, 2, 3, 4, 5],
          "startTime": "17:00",
          "endTime": "21:00"
        }
      ]
    }
  ]
}

​
Update a Schedule

Update an existing schedule. 
curl --request PATCH \
  --url https://api.cal.com/v2/schedules/{scheduleId} \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Updated Schedule",
    "availability": [
      {
        "days": [1, 2, 3, 4],
        "startTime": "10:00",
        "endTime": "18:00"
      }
    ]
  }'

​
Path Parameters

​
scheduleId
number
required
The ID of the schedule to update

​
Request Body

All fields from the create endpoint are supported. Only include fields you want to update.

​
Delete a Schedule

Delete a schedule. 
curl --request DELETE \
  --url https://api.cal.com/v2/schedules/{scheduleId} \
  --header 'Authorization: Bearer <api-key>' \
  --header 'cal-api-version: 2024-06-11'

​
Path Parameters

​
scheduleId
number
required
The ID of the schedule to delete

​
Response

{
  "status": "success"
}

​
Day Numbers

When specifying days in the availability array, use these numbers:
  • 0 = Sunday
  • 1 = Monday
  • 2 = Tuesday
  • 3 = Wednesday
  • 4 = Thursday
  • 5 = Friday
  • 6 = Saturday

​
Time Format

Use 24-hour time format for start and end times:
  • Morning: “09:00”, “08:30”
  • Afternoon: “13:00”, “14:30”
  • Evening: “17:00”, “20:00”

​
Example Schedules

​
Standard Business Hours (9-5, Weekdays)

{
  "name": "Business Hours",
  "timeZone": "America/New_York",
  "isDefault": true,
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "17:00"
    }
  ]
}

​
Split Schedule (Morning and Afternoon)

{
  "name": "Split Schedule",
  "timeZone": "Europe/London",
  "isDefault": false,
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "12:00"
    },
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "14:00",
      "endTime": "18:00"
    }
  ]
}

​
Weekend Availability

{
  "name": "Weekends",
  "timeZone": "America/Los_Angeles",
  "isDefault": false,
  "availability": [
    {
      "days": [0, 6],
      "startTime": "10:00",
      "endTime": "16:00"
    }
  ]
}

​
Managed Users

For platform customers managing users:
  1. Pass timezone when creating managed users to automatically create a default schedule (Monday-Friday, 9AM-5PM)
  2. Without a default schedule, users cannot be booked or manage availability
  3. Users can modify their schedule via the AvailabilitySettings atom

​
Linking Schedules to Event Types

After creating a schedule, you can link it to event types: 
PATCH /v2/event-types/{eventTypeId}
{
  "scheduleId": 456
}
If no scheduleId is specified, the event type uses the user’s default schedule.

​
Notes

  • Each user must have exactly one default schedule
  • Schedules are in the user’s specified timezone
  • Event types without a specific scheduleId use the default schedule
  • You can create multiple schedules for different availability patterns
  • Use overrides for date-specific changes (holidays, time off, etc.)

Build docs developers (and LLMs) love

Get started for freeTalk to us