Cal.com Schedules API

openapi: 3.2.0
info:
  title: Cal.com API v2 Schedules API
  description: ''
  version: 1.0.0
  contact: {}
servers: []
tags:
- name: Schedules
paths:
  /v2/schedules:
    post:
      description: 'Create a schedule for the authenticated user.


        The point of creating schedules is for event types to be available at specific times.


        The first goal of schedules is to have a default schedule. If you are platform customer and created managed users, then it is important to note that each managed user should have a default schedule.

        1. If you passed `timeZone` when creating managed user, then the default schedule from Monday to Friday from 9AM to 5PM will be created with that timezone. The managed user can then change the default schedule via the `AvailabilitySettings` atom.

        2. If you did not, then we assume you want the user to have this specific schedule right away. You should create a default schedule by specifying

        `"isDefault": true` in the request body. Until the user has a default schedule the user can''t be booked nor manage their schedule via the AvailabilitySettings atom.


        The second goal of schedules is to create another schedule that event types can point to. This is useful for when an event is booked because availability is not checked against the default schedule but instead against that specific schedule.

        After creating a non-default schedule, you can update an event type to point to that schedule via the PATCH `event-types/{eventTypeId}` endpoint.


        When specifying start time and end time for each day use the 24 hour format e.g. 08:00, 15:00 etc.


        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 `SCHEDULE_WRITE` scope is required.'
      operationId: SchedulesController_2024_06_11_createSchedule
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_, managed user access token, or OAuth access token
        required: true
        schema:
          type: string
      - name: cal-api-version
        in: header
        description: Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.
        required: true
        schema:
          type: string
          example: '2024-06-11'
          default: '2024-06-11'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduleInput_2024_06_11'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateScheduleOutput_2024_06_11'
      summary: Create a schedule
      tags:
      - Schedules
      x-mcp:
        name: create_schedule
        guidance: 'Create a schedule. Required: name, timeZone, isDefault. Each user should have exactly one default schedule. Supports availability slots and date-specific overrides.'
      x-oauth-scopes:
      - SCHEDULE_WRITE
    get:
      description: 'Get all schedules of the authenticated user.


        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 `SCHEDULE_READ` scope is required.'
      operationId: SchedulesController_2024_06_11_getSchedules
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_, managed user access token, or OAuth access token
        required: true
        schema:
          type: string
      - name: cal-api-version
        in: header
        description: Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.
        required: true
        schema:
          type: string
          example: '2024-06-11'
          default: '2024-06-11'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSchedulesOutput_2024_06_11'
      summary: Get all schedules
      tags:
      - Schedules
      x-mcp:
        name: get_schedules
        guidance: List all schedules of the authenticated user.
      x-oauth-scopes:
      - SCHEDULE_READ
  /v2/schedules/default:
    get:
      description: 'Get the default schedule of the authenticated user.


        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 `SCHEDULE_READ` scope is required.'
      operationId: SchedulesController_2024_06_11_getDefaultSchedule
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_, managed user access token, or OAuth access token
        required: true
        schema:
          type: string
      - name: cal-api-version
        in: header
        description: Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.
        required: true
        schema:
          type: string
          example: '2024-06-11'
          default: '2024-06-11'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDefaultScheduleOutput_2024_06_11'
      summary: Get default schedule
      tags:
      - Schedules
      x-mcp:
        name: get_default_schedule
        guidance: Get the authenticated user's default schedule.
      x-oauth-scopes:
      - SCHEDULE_READ
  /v2/schedules/{scheduleId}:
    get:
      description: '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 `SCHEDULE_READ` scope is required.'
      operationId: SchedulesController_2024_06_11_getSchedule
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_, managed user access token, or OAuth access token
        required: true
        schema:
          type: string
      - name: cal-api-version
        in: header
        description: Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.
        required: true
        schema:
          type: string
          example: '2024-06-11'
          default: '2024-06-11'
      - name: scheduleId
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScheduleOutput_2024_06_11'
      summary: Get a schedule
      tags:
      - Schedules
      x-mcp:
        name: get_schedule
        guidance: Get a schedule by its numeric ID. Returns availability slots and overrides.
      x-oauth-scopes:
      - SCHEDULE_READ
    patch:
      description: '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 `SCHEDULE_WRITE` scope is required.'
      operationId: SchedulesController_2024_06_11_updateSchedule
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_, managed user access token, or OAuth access token
        required: true
        schema:
          type: string
      - name: cal-api-version
        in: header
        description: Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.
        required: true
        schema:
          type: string
          example: '2024-06-11'
          default: '2024-06-11'
      - name: scheduleId
        required: true
        in: path
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleInput_2024_06_11'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateScheduleOutput_2024_06_11'
      summary: Update a schedule
      tags:
      - Schedules
      x-mcp:
        name: update_schedule
        guidance: Update an existing schedule. Array fields (availability, overrides) replace all existing entries.
      x-oauth-scopes:
      - SCHEDULE_WRITE
    delete:
      description: '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 `SCHEDULE_WRITE` scope is required.'
      operationId: SchedulesController_2024_06_11_deleteSchedule
      parameters:
      - name: Authorization
        in: header
        description: value must be `Bearer <token>` where `<token>` is api key prefixed with cal_, managed user access token, or OAuth access token
        required: true
        schema:
          type: string
      - name: cal-api-version
        in: header
        description: Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.
        required: true
        schema:
          type: string
          example: '2024-06-11'
          default: '2024-06-11'
      - name: scheduleId
        required: true
        in: path
        schema:
          type: number
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteScheduleOutput_2024_06_11'
      summary: Delete a schedule
      tags:
      - Schedules
      x-mcp:
        name: delete_schedule
        guidance: Delete a schedule by its numeric ID. This action is irreversible, confirm with the user before proceeding.
      x-oauth-scopes:
      - SCHEDULE_WRITE
components:
  schemas:
    CreateScheduleOutput_2024_06_11:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/ScheduleOutput_2024_06_11'
      required:
      - status
      - data
    ScheduleOverrideInput_2024_06_11:
      type: object
      properties:
        date:
          type: string
          example: '2024-05-20'
        startTime:
          type: string
          example: '12:00'
          description: startTime must be a valid time in format HH:MM e.g. 12:00
        endTime:
          type: string
          example: '13:00'
          description: endTime must be a valid time in format HH:MM e.g. 13:00
      required:
      - date
      - startTime
      - endTime
    UpdateScheduleOutput_2024_06_11:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/ScheduleOutput_2024_06_11'
      required:
      - status
      - data
    ScheduleAvailabilityInput_2024_06_11:
      type: object
      properties:
        days:
          type: array
          items:
            type: string
            enum:
            - Monday
            - Tuesday
            - Wednesday
            - Thursday
            - Friday
            - Saturday
            - Sunday
          example:
          - Monday
          - Tuesday
          description: Array of days when schedule is active.
        startTime:
          type: string
          example: 08:00
          description: startTime must be a valid time in format HH:MM e.g. 08:00
        endTime:
          type: string
          example: '15:00'
          description: endTime must be a valid time in format HH:MM e.g. 15:00
      required:
      - days
      - startTime
      - endTime
    UpdateScheduleInput_2024_06_11:
      type: object
      properties:
        name:
          type: string
          example: One-on-one coaching
        timeZone:
          type: string
          example: Europe/Rome
        availability:
          example:
          - days:
            - Monday
            - Tuesday
            startTime: 09:00
            endTime: '10:00'
          type: array
          items:
            $ref: '#/components/schemas/ScheduleAvailabilityInput_2024_06_11'
        isDefault:
          type: boolean
          example: true
        overrides:
          example:
          - date: '2024-05-20'
            startTime: '12:00'
            endTime: '14:00'
          type: array
          items:
            $ref: '#/components/schemas/ScheduleOverrideInput_2024_06_11'
    CreateScheduleInput_2024_06_11:
      type: object
      properties:
        name:
          type: string
          example: Catch up hours
        timeZone:
          type: string
          example: Europe/Rome
          description: Timezone is used to calculate available times when an event using the schedule is booked.
        availability:
          description: Each object contains days and times when the user is available. If not passed, the default availability is Monday to Friday from 09:00 to 17:00.
          example:
          - days:
            - Monday
            - Tuesday
            startTime: '17:00'
            endTime: '19:00'
          - days:
            - Wednesday
            - Thursday
            startTime: '16:00'
            endTime: '20:00'
          type: array
          items:
            $ref: '#/components/schemas/ScheduleAvailabilityInput_2024_06_11'
        isDefault:
          type: boolean
          example: true
          description: "Each user should have 1 default schedule. If you specified `timeZone` when creating managed user, then the default schedule will be created with that timezone.\n    Default schedule means that if an event type is not tied to a specific schedule then the default schedule is used."
        overrides:
          description: Need to change availability for a specific date? Add an override.
          example:
          - date: '2024-05-20'
            startTime: '18:00'
            endTime: '21:00'
          type: array
          items:
            $ref: '#/components/schemas/ScheduleOverrideInput_2024_06_11'
      required:
      - name
      - timeZone
      - isDefault
    ScheduleOutput_2024_06_11:
      type: object
      properties:
        id:
          type: number
          example: 254
        ownerId:
          type: number
          example: 478
        name:
          type: string
          example: Catch up hours
        timeZone:
          type: string
          example: Europe/Rome
        availability:
          example:
          - days:
            - Monday
            - Tuesday
            startTime: '17:00'
            endTime: '19:00'
          - days:
            - Wednesday
            - Thursday
            startTime: '16:00'
            endTime: '20:00'
          type: array
          items:
            $ref: '#/components/schemas/ScheduleAvailabilityInput_2024_06_11'
        isDefault:
          type: boolean
          example: true
        overrides:
          example:
          - date: '2024-05-20'
            startTime: '18:00'
            endTime: '21:00'
          type: array
          items:
            $ref: '#/components/schemas/ScheduleOverrideInput_2024_06_11'
      required:
      - id
      - ownerId
      - name
      - timeZone
      - availability
      - isDefault
      - overrides
    DeleteScheduleOutput_2024_06_11:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
      required:
      - status
    GetScheduleOutput_2024_06_11:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/ScheduleOutput_2024_06_11'
      required:
      - status
      - data
    GetSchedulesOutput_2024_06_11:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScheduleOutput_2024_06_11'
      required:
      - status
      - data
    GetDefaultScheduleOutput_2024_06_11:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/ScheduleOutput_2024_06_11'
      required:
      - status
      - data
x-provenance:
  method: harvested
  publisher: Cal.com
  source: https://cal.com/docs/api-reference/v2/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)