> ## 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.

# Schedules

> Manage availability schedules through the Cal.com API

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:

```bash theme={null}
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.

<CodeGroup>
  ```bash cURL - Default Schedule theme={null}
  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"
        }
      ]
    }'
  ```

  ```bash cURL - Custom Schedule theme={null}
  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": "Evening Hours",
      "timeZone": "America/New_York",
      "isDefault": false,
      "availability": [
        {
          "days": [1, 2, 3, 4, 5],
          "startTime": "17:00",
          "endTime": "21:00"
        }
      ]
    }'
  ```
</CodeGroup>

### Request Body

<ParamField body="name" type="string" required>
  Schedule name (e.g., "Default Schedule", "Evening Hours")
</ParamField>

<ParamField body="timeZone" type="string" required>
  IANA timezone (e.g., "America/New\_York", "Europe/London")
</ParamField>

<ParamField body="isDefault" type="boolean">
  Whether this is the default schedule. Each user should have exactly one default schedule.
</ParamField>

<ParamField body="availability" type="array" required>
  Array of availability rules

  <Expandable>
    <ParamField body="days" type="array">
      Array of day numbers: 0 (Sunday) through 6 (Saturday). Example: \[1, 2, 3, 4, 5] for weekdays.
    </ParamField>

    <ParamField body="startTime" type="string">
      Start time in 24-hour format (e.g., "09:00", "17:00")
    </ParamField>

    <ParamField body="endTime" type="string">
      End time in 24-hour format (e.g., "17:00", "21:00")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="overrides" type="array">
  Date-specific overrides

  <Expandable>
    <ParamField body="date" type="string">
      Date in YYYY-MM-DD format
    </ParamField>

    <ParamField body="startTime" type="string">
      Start time override
    </ParamField>

    <ParamField body="endTime" type="string">
      End time override
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="status" type="string">
  Status of the response ("success")
</ResponseField>

<ResponseField name="data" type="object">
  Schedule details

  <Expandable>
    <ResponseField name="id" type="number">
      Schedule ID
    </ResponseField>

    <ResponseField name="name" type="string">
      Schedule name
    </ResponseField>

    <ResponseField name="timeZone" type="string">
      Schedule timezone
    </ResponseField>

    <ResponseField name="isDefault" type="boolean">
      Whether this is the default schedule
    </ResponseField>

    <ResponseField name="availability" type="array">
      Availability rules
    </ResponseField>
  </Expandable>
</ResponseField>

## Get Default Schedule

Retrieve the authenticated user's default schedule.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cal.com/v2/schedules/default \
    --header 'Authorization: Bearer <api-key>' \
    --header 'cal-api-version: 2024-06-11'
  ```
</CodeGroup>

### Response

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

## Get a Schedule

Retrieve a specific schedule by ID.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cal.com/v2/schedules/{scheduleId} \
    --header 'Authorization: Bearer <api-key>' \
    --header 'cal-api-version: 2024-06-11'
  ```
</CodeGroup>

### Path Parameters

<ParamField path="scheduleId" type="number" required>
  The ID of the schedule to retrieve
</ParamField>

## Get All Schedules

List all schedules for the authenticated user.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.cal.com/v2/schedules \
    --header 'Authorization: Bearer <api-key>' \
    --header 'cal-api-version: 2024-06-11'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```
</CodeGroup>

### Path Parameters

<ParamField path="scheduleId" type="number" required>
  The ID of the schedule to update
</ParamField>

### Request Body

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

## Delete a Schedule

Delete a schedule.

<CodeGroup>
  ```bash cURL theme={null}
  curl --request DELETE \
    --url https://api.cal.com/v2/schedules/{scheduleId} \
    --header 'Authorization: Bearer <api-key>' \
    --header 'cal-api-version: 2024-06-11'
  ```
</CodeGroup>

### Path Parameters

<ParamField path="scheduleId" type="number" required>
  The ID of the schedule to delete
</ParamField>

### Response

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```bash theme={null}
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.)