Cal.com Cal Unified Calendars API

openapi: 3.2.0
info:
  title: Cal.com API v2 Cal Unified Calendars API
  description: ''
  version: 1.0.0
  contact: {}
servers: []
tags:
- name: Cal Unified Calendars
paths:
  /v2/calendars/{calendar}/event/{eventUid}:
    get:
      description: Returns detailed information about a meeting including attendance metrics. If accessed using an OAuth access token, the `APPS_READ` scope is required.
      operationId: CalUnifiedCalendarsController_getCalendarEventDetails
      parameters:
      - name: calendar
        required: true
        in: path
        schema:
          enum:
          - google
          type: string
      - name: eventUid
        required: true
        in: path
        description: 'The Google Calendar event ID. You can retrieve this by getting booking references from the following endpoints:


          - For team events: https://cal.com/docs/api-reference/v2/orgs-teams-bookings/get-booking-references-for-a-booking


          - For user events: https://cal.com/docs/api-reference/v2/bookings/get-booking-references-for-a-booking'
        schema:
          type: string
      - 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
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUnifiedCalendarEventOutput'
      summary: Get meeting details from calendar
      tags:
      - Cal Unified Calendars
      x-oauth-scopes:
      - APPS_READ
  /v2/calendars/{calendar}/events/{eventUid}:
    patch:
      description: Updates event information in the specified calendar provider. If accessed using an OAuth access token, the `APPS_WRITE` scope is required.
      operationId: CalUnifiedCalendarsController_updateCalendarEvent
      parameters:
      - name: calendar
        required: true
        in: path
        schema:
          enum:
          - google
          type: string
      - name: eventUid
        required: true
        in: path
        description: 'The Google Calendar event ID. You can retrieve this by getting booking references from the following endpoints:


          - For team events: https://cal.com/docs/api-reference/v2/orgs-teams-bookings/get-booking-references-for-a-booking


          - For user events: https://cal.com/docs/api-reference/v2/bookings/get-booking-references-for-a-booking'
        schema:
          type: string
      - 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
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUnifiedCalendarEventInput'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUnifiedCalendarEventOutput'
      summary: Update meeting details in calendar
      tags:
      - Cal Unified Calendars
      x-oauth-scopes:
      - APPS_WRITE
components:
  schemas:
    CalendarEventSipLocation:
      type: object
      properties:
        type:
          type: string
          default: sip
          enum:
          - sip
          description: Indicates this is a SIP (Session Initiation Protocol) conference location
        url:
          type: string
          description: SIP URL for joining the conference
        label:
          type:
          - string
          - 'null'
          description: Display name for the SIP conference
        pin:
          type:
          - string
          - 'null'
          description: PIN number required for the SIP conference
        password:
          type:
          - string
          - 'null'
          description: Password required for the SIP conference
      required:
      - type
      - url
    GetUnifiedCalendarEventOutput:
      type: object
      properties:
        status:
          enum:
          - success
          - error
          type: string
          example: success
        data:
          $ref: '#/components/schemas/UnifiedCalendarEventOutput'
      required:
      - status
      - data
    UpdateCalendarEventAttendee:
      type: object
      properties:
        email:
          type: string
          description: Email address of the attendee
        name:
          type: string
          description: Display name of the attendee
        responseStatus:
          description: Response status of the attendee
          allOf:
          - $ref: '#/components/schemas/CalendarEventResponseStatus'
        self:
          type:
          - boolean
          - 'null'
          description: Indicates if this attendee is the current user
        optional:
          type:
          - boolean
          - 'null'
          description: Indicates if this attendee's attendance is optional
        host:
          type:
          - boolean
          - 'null'
          description: Indicates if this attendee is the host
    CalendarEventMoreLocation:
      type: object
      properties:
        type:
          type: string
          default: more
          enum:
          - more
          description: Indicates this is an additional conference location type
        url:
          type: string
          description: URL for accessing this location
        label:
          type:
          - string
          - 'null'
          description: Display name for this location
      required:
      - type
      - url
    UpdateUnifiedCalendarEventInput:
      type: object
      properties:
        start:
          type: object
          properties:
            time:
              type: string
              format: date-time
            timeZone:
              type: string
          description: Start date and time of the calendar event with timezone information
        end:
          type: object
          properties:
            time:
              type: string
              format: date-time
            timeZone:
              type: string
          description: End date and time of the calendar event with timezone information
        title:
          type: string
          description: Title of the calendar event
        description:
          type:
          - string
          - 'null'
          description: Detailed description of the calendar event
        attendees:
          description: 'List of attendees. CAUTION: You must pass the entire array with all updated values. Any attendees not included in this array will be removed from the event.'
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/UpdateCalendarEventAttendee'
        status:
          description: Status of the event (accepted, pending, declined, cancelled)
          example: accepted
          allOf:
          - $ref: '#/components/schemas/CalendarEventStatus'
    CalendarEventAttendee:
      type: object
      properties:
        email:
          type: string
          description: Email address of the attendee
        name:
          type: string
          description: Display name of the attendee
        responseStatus:
          description: Attendee's response to the invitation
          example: accepted
          allOf:
          - $ref: '#/components/schemas/CalendarEventResponseStatus'
        self:
          type:
          - boolean
          - 'null'
          description: Indicates if this attendee is the current user
        optional:
          type:
          - boolean
          - 'null'
          description: Indicates if this attendee's attendance is optional
        host:
          type:
          - boolean
          - 'null'
          description: Indicates if this attendee is the host
      required:
      - email
    calendarEventOwner:
      type: object
      properties:
        email:
          type: string
          description: Email address of the event host
        name:
          type:
          - string
          - 'null'
          description: Display name of the event host
      required:
      - email
    UnifiedCalendarEventOutput:
      type: object
      properties:
        start:
          type: object
          properties:
            time:
              type: string
              format: date-time
            timeZone:
              type: string
          description: Start date and time of the calendar event with timezone information
        end:
          type: object
          properties:
            time:
              type: string
              format: date-time
            timeZone:
              type: string
          description: End date and time of the calendar event with timezone information
        id:
          type: string
          description: Unique identifier of the calendar event
        title:
          type: string
          description: Title of the calendar event
        description:
          type:
          - string
          - 'null'
          description: Detailed description of the calendar event
        locations:
          type:
          - array
          - 'null'
          items:
            oneOf:
            - title: Video
              $ref: '#/components/schemas/CalendarEventVideoLocation'
            - title: Phone
              $ref: '#/components/schemas/CalendarEventPhoneLocation'
            - title: SIP
              $ref: '#/components/schemas/CalendarEventSipLocation'
            - title: More
              $ref: '#/components/schemas/CalendarEventMoreLocation'
            discriminator:
              propertyName: type
          description: Conference locations with entry points (video, phone, sip, more)
        attendees:
          description: List of attendees with their response status
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CalendarEventAttendee'
        status:
          description: Status of the event (accepted, pending, declined, cancelled)
          example: accepted
          allOf:
          - $ref: '#/components/schemas/CalendarEventStatus'
        hosts:
          description: Information about the event hosts (organizers)
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CalendarEventHost'
        calendarEventOwner:
          description: The calendar account that owns this event. This is the primary calendar where the event is stored and cannot be modified without appropriate permissions. Changing this would require moving the event to a different calendar
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/calendarEventOwner'
        source:
          description: Calendar integration source (e.g., Google Calendar, Office 365, Apple Calendar). Currently only Google Calendar is supported.
          example: google
          allOf:
          - $ref: '#/components/schemas/CalendarSource'
      required:
      - start
      - end
      - id
      - title
      - source
    CalendarEventPhoneLocation:
      type: object
      properties:
        type:
          type: string
          default: phone
          enum:
          - phone
          description: Indicates this is a phone conference location
        url:
          type: string
          description: Phone number or URL for dialing into the conference
        label:
          type:
          - string
          - 'null'
          description: Display name for the phone conference
        pin:
          type:
          - string
          - 'null'
          description: PIN number required for the phone conference
        password:
          type:
          - string
          - 'null'
          description: Password required for the phone conference
        accessCode:
          type:
          - string
          - 'null'
          description: Access code required for the phone conference
        regionCode:
          type:
          - string
          - 'null'
          description: Country/region code for the phone number
      required:
      - type
      - url
    CalendarEventVideoLocation:
      type: object
      properties:
        type:
          type: string
          default: video
          enum:
          - video
          description: Indicates this is a video conference location
        url:
          type: string
          description: URL for joining the video conference
        label:
          type:
          - string
          - 'null'
          description: Display name for the video conference
        password:
          type:
          - string
          - 'null'
          description: Password required to join the video conference
        meetingCode:
          type:
          - string
          - 'null'
          description: Meeting code or ID required to join the conference
        accessCode:
          type:
          - string
          - 'null'
          description: Access code required to join the conference
      required:
      - type
      - url
    CalendarEventStatus:
      type: string
      enum:
      - accepted
      - pending
      - declined
      - cancelled
      description: Status of the event (accepted, pending, declined, cancelled)
    CalendarEventResponseStatus:
      type: string
      enum:
      - accepted
      - pending
      - declined
      - needsAction
      description: Attendee's response to the invitation
    CalendarEventHost:
      type: object
      properties:
        email:
          type: string
          description: Email address of the event host
        name:
          type:
          - string
          - 'null'
          description: Display name of the event host
        responseStatus:
          description: Host's response to the invitation
          example: accepted
          allOf:
          - $ref: '#/components/schemas/CalendarEventResponseStatus'
      required:
      - email
    CalendarSource:
      type: string
      enum:
      - google
      - office365
      - apple
      description: Calendar integration source (e.g., Google Calendar, Office 365, Apple Calendar). Currently only Google Calendar is supported.
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)