### Quick Start with Docker Compose

Source: https://cal.com/docs/developing/local-development

Initiates a local development environment using Docker and Docker Compose, including a PostgreSQL instance and test users. Requires Docker to be installed.

```bash
yarn dx
```

--------------------------------

### Start Development Server

Source: https://cal.com/docs/developing/guides/api/how-to-setup-api-in-a-local-instance

Start the Cal.com development server using `yarn dev` to prepare for API key creation.

```shell
yarn dev
```

--------------------------------

### Install Cal.com CLI with curl

Source: https://cal.com/docs/agents

Install the Cal.com CLI by downloading and executing the installation script with curl. This is an alternative installation method.

```bash
curl -fsSL https://cal.com/install.sh | bash
```

--------------------------------

### Meeting Started Webhook Example

Source: https://cal.com/docs/developing/guides/automation/webhooks

The MEETING_STARTED webhook has a flat payload structure. This webhook fires automatically at the booking's scheduled start time.

```json
{
          "triggerEvent": "MEETING_STARTED",
          "id": 100,
          "uid": "unique-booking-identifier",
          "idempotencyKey": "00000000-0000-0000-0000-000000000000",
          "userId": 10,
          "userPrimaryEmail": "organizer@example.com",
          "eventTypeId": 50,
          "title": "Strategy Session: Organizer & Guest",
          "description": "",
          "customInputs": {},
          "responses": {
            "name": {
              "label": "your_name",
              "value": "Guest User",
              "isHidden": false
            },
            "email": {
              "label": "email_address",
              "value": "guest@example.com",
              "isHidden": false
            },
            "attendeePhoneNumber": {
              "label": "phone_number",
              "isHidden": true
            },
            "location": {
              "label": "location",
              "value": {
                "optionValue": "",
                "value": "integrations:video-provider"
              },
              "isHidden": false
            },
            "title": {
              "label": "what_is_this_meeting_about",
              "isHidden": true
            },
            "notes": {
              "label": "additional_notes",
              "isHidden": false
            },
            "guests": {
              "label": "additional_guests",
              "value": [
                "additional-guest@example.com"
              ],
              "isHidden": false
            },
            "rescheduleReason": {
              "label": "reason_for_reschedule",
              "isHidden": false
            }
          },
          "startTime": "2024-01-01T10:00:00.000Z",
          "endTime": "2024-01-01T10:15:00.000Z",
          "location": "integrations:video-provider",
          "createdAt": "2024-01-01T09:45:00.000Z",
          "updatedAt": "2024-01-01T09:45:00.000Z",
          "status": "ACCEPTED",
          "paid": false,
          "destinationCalendarId": null,
          "cancellationReason": null,
          "rejectionReason": null,
          "reassignReason": null,
          "reassignById": null,
          "dynamicEventSlugRef": null,
          "dynamicGroupSlugRef": null,
          "rescheduled": null,
          "fromReschedule": null,
          "recurringEventId": null,
          "smsReminderNumber": null,
          "scheduledJobs": [],
          "metadata": {},
          "isRecorded": false
        }
```

--------------------------------

### Check-Then-Charge Pattern Example

Source: https://cal.com/docs/agents

An example demonstrating the recommended pattern of checking available credits before performing an action and then charging them upon completion.

```APIDOC
## Example: Check-Then-Charge Pattern

### Description
This example illustrates a common workflow for AI agents: first checking credit availability, then executing a task, and finally charging the credits. It emphasizes the importance of `externalRef` for preventing duplicate charges.

### Code Example
```typescript
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()}`
  })
});
```
```

--------------------------------

### Install Project Dependencies

Source: https://cal.com/docs/developing/open-source-contribution/introduction

Installs all necessary project dependencies using Yarn. Run this after cloning the repository or pulling changes that affect `package.json`.

```bash
yarn
```

--------------------------------

### Example of defaultFormValues for Address Field

Source: https://cal.com/docs/api-reference/v2/teams-event-types/create-an-event-type

This example shows how to prefill the address field using the defaultFormValues prop. Refer to the booking field guide for more details.

```javascript
defaultFormValues={{address: 'mainstreat 10, new york'}}
```

--------------------------------

### Copy API Environment Example Files

Source: https://cal.com/docs/developing/local-development

Copies the example .env files for API versions v1 and v2, and the root .env file. This is the first step before configuring API settings.

```bash
cp apps/api/{version}/.env.example apps/api/{version}/.env
cp .env.example .env
```

--------------------------------

### Install Cal.com CLI with npm

Source: https://cal.com/docs/agents

Install the Cal.com CLI globally using npm. This is the recommended method for agents that can execute commands on a machine.

```bash
npm install -g @calcom/cli
```

--------------------------------

### Start API v2 Server

Source: https://cal.com/docs/developing/guides/api/how-to-setup-api-in-a-local-instance

Start the API v2 server using `yarn workspace @calcom/api-v2 dev` to begin local API testing.

```shell
yarn workspace @calcom/api-v2 dev
```

--------------------------------

### Example API Response for User Creation

Source: https://cal.com/docs/platform/quickstart

This is an example of a successful response when creating a managed user. It includes the user's basic information, an access token, and a refresh token.

```javascript
{
  "status": "success",
  "data": {
    "user": {
      "id": 179,
      "email": "bob@example.com",
      "username": "bob"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzX3Rva2VuIiwiY2xpZW50SWQiOiJjbHUxZmNtYjEwMDAxa2hyN3g3ZHJleWw0Iiwib3duZXJJZCI6MTc5LCJpYXQiOjE3MTE0NDI3OTR9.EsC3JRPHQnigcp_HSijKCIp8EgcWs2kj4AFxYXYc9sM",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicmVmcmVzaF90b2tlbiIsImNsaWVudElkIjoiY2x1MWZjbWIxMDAwMWtocjd4N2RyZXlsNCIsIm93bmVySWQiOjE3OSwiaWF0IjoxNzExNDQyNzk0fQ.GjklEucgey8yWMoGz7ABntbxYdiqqQFPooQjqGd3B5I"
  }
}
```

--------------------------------

### Install Cal.com Atoms Package

Source: https://cal.com/docs/atoms/setup

Installs the Cal.com Atoms package using npm, yarn, or pnpm. Choose the command that matches your project's package manager.

```bash
npm i @calcom/atoms
```

```bash
yarn add @calcom/atoms
```

```bash
pnpm add @calcom/atoms
```

--------------------------------

### Redirect Mode URL Example

Source: https://cal.com/docs/api-reference/v2/oauth

This is an example of the URL structure when using redirect mode. The browser navigates to your `redirectUri` after the user completes onboarding and grants access.

```url
https://your-app.com/cal/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE
```

--------------------------------

### Install Cal.com Atoms with yarn

Source: https://cal.com/docs/platform/quickstart

Install the atoms package using yarn. This package provides customizable UI components for scheduling.

```bash
yarn add @calcom/atoms
```

--------------------------------

### Install @calcom/atoms for Onboarding Embed

Source: https://cal.com/docs/api-reference/v2/oauth

Install the @calcom/atoms package to use the OnboardingEmbed React component for embedding Cal.com account creation and OAuth authorization.

```bash
npm install @calcom/atoms
```

--------------------------------

### Navigate to Project Directory

Source: https://cal.com/docs/developing/local-development

Change into the newly cloned Cal.com directory to proceed with the setup.

```bash
cd cal.com
```

--------------------------------

### Get Bookings After Start Date

Source: https://cal.com/docs/api-reference/v2/bookings/get-all-bookings

Filters bookings that start after a specified date and time string.

```http
GET /v2/bookings?afterStart=2025-03-07T10:00:00.000Z HTTP/1.1
Host: api.cal.com
cal-api-version: 2026-05-01
```

--------------------------------

### Copy API Environment Files

Source: https://cal.com/docs/self-hosting/installation

Before setting up the API, copy the example environment files to their active counterparts. This sets up the necessary configuration.

```bash
cp apps/api/v2/.env.example apps/api/v2/.env
cp .env.example .env
```

--------------------------------

### Default Form Values Example

Source: https://cal.com/docs/api-reference/v2/event-types/update-an-event-type

Pass the slug used for a booking field to the defaultFormValues prop with the desired value. Refer to the booking field guide for more details.

```javascript
defaultFormValues={{videourl: 'https://caltube.com/123'}}
```

--------------------------------

### Copy .env.example to .env

Source: https://cal.com/docs/developing/guides/api/how-to-setup-api-in-a-local-instance

Copy the example environment file to `.env` to configure the API v2 environment.

```shell
cp apps/api/v2/.env.example apps/api/v2/.env
```

--------------------------------

### Show Specific Tabs in Event Type Settings

Source: https://cal.com/docs/atoms/event-type

Customize the displayed tabs by providing a subset of the available tab names to the 'tabs' prop. This example shows only 'setup', 'limits', and 'availability'.

```javascript
// Example: Show only setup, limits, and availability tabs
<EventTypeSettings
  id={eventTypeId}
  tabs={["setup", "limits", "availability"]}
  onSuccess={(eventType) => {
    console.log("EventType settings updated successfully", eventType);
  }}
/>
```

--------------------------------

### Deploy Database with Prisma

Source: https://cal.com/docs/developing/local-development

Use this command to set up your database schema based on the Prisma schema file. Ensure you are in the correct workspace.

```bash
yarn workspace @calcom/prisma db-deploy
```

--------------------------------

### Get Team Bookings

Source: https://cal.com/docs/api-reference/v2/teams-bookings/get-team-bookings

Fetches a list of bookings for a given team. Supports filtering by status, attendee details, event type, and date ranges, as well as sorting by start, end, or creation times.

```APIDOC
## GET /v2/teams/{teamId}/bookings

### Description
Retrieves a list of bookings for a specific team. Access requires the `TEAM_BOOKING_READ` scope if using an OAuth token.

### Method
GET

### Endpoint
/v2/teams/{teamId}/bookings

### Parameters
#### Path Parameters
- **teamId** (string) - Required - The ID of the team whose bookings are to be retrieved.

#### Header Parameters
- **Authorization** (string) - Required - `Bearer <token>` where `<token>` is an API key prefixed with `cal_`.

#### Query Parameters
- **status** (array of strings) - Optional - Filter bookings by status. Multiple statuses can be separated by a comma. Allowed values: `upcoming`, `recurring`, `past`, `cancelled`, `unconfirmed`.
- **attendeeEmail** (string) - Optional - Filter bookings by the attendee's email address.
- **attendeeName** (string) - Optional - Filter bookings by the attendee's name.
- **bookingUid** (string) - Optional - Filter bookings by the booking Uid.
- **eventTypeIds** (string) - Optional - Filter bookings by event type IDs. IDs must be separated by a comma.
- **eventTypeId** (string) - Optional - Filter bookings by a single event type ID.
- **afterStart** (string) - Optional - Filter bookings with a start time after this date string (ISO 8601 format).
- **beforeEnd** (string) - Optional - Filter bookings with an end time before this date string (ISO 8601 format).
- **afterCreatedAt** (string) - Optional - Filter bookings created after this date string (ISO 8601 format).
- **beforeCreatedAt** (string) - Optional - Filter bookings created before this date string (ISO 8601 format).
- **afterUpdatedAt** (string) - Optional - Filter bookings updated after this date string (ISO 8601 format).
- **beforeUpdatedAt** (string) - Optional - Filter bookings updated before this date string (ISO 8601 format).
- **sortStart** (string) - Optional - Sort results by start time. Allowed values: `asc`, `desc`.
- **sortEnd** (string) - Optional - Sort results by end time. Allowed values: `asc`, `desc`.
- **sortCreated** (string) - Optional - Sort results by creation time. Allowed values: `asc`, `desc`.

### Response
#### Success Response (200)
- **bookings** (array) - A list of booking objects.
  - Each booking object contains details such as `id`, `uid`, `startTime`, `endTime`, `createdAt`, `updatedAt`, `status`, `attendee`, `event` etc.

#### Response Example
{
  "bookings": [
    {
      "id": 123,
      "uid": "2NtaeaVcKfpmSZ4CthFdfk",
      "startTime": "2025-03-07T10:00:00.000Z",
      "endTime": "2025-03-07T11:00:00.000Z",
      "createdAt": "2025-03-01T09:00:00.000Z",
      "updatedAt": "2025-03-01T09:00:00.000Z",
      "status": "upcoming",
      "attendee": {
        "name": "John Doe",
        "email": "example@domain.com"
      },
      "event": {
        "id": 100,
        "title": "Meeting"
      }
    }
  ]
}
```

--------------------------------

### Get Organization Team Bookings

Source: https://cal.com/docs/api-reference/v2/orgs-teams-bookings/get-organization-team-bookings

Fetches a list of bookings for a specified organization and team. This endpoint returns detailed information about each booking, such as title, description, start and end times, attendees, and custom booking fields.

```APIDOC
## GET /orgs/{orgId}/teams/{teamId}/bookings

### Description
Retrieves a list of bookings for a specific organization's team. This endpoint returns detailed information about each booking, such as title, description, start and end times, attendees, and custom booking fields.

### Method
GET

### Endpoint
/orgs/{orgId}/teams/{teamId}/bookings

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The unique identifier for the organization.
- **teamId** (string) - Required - The unique identifier for the team within the organization.

#### Query Parameters
- **status** (string) - Optional - Filters bookings by their status (e.g., 'accepted', 'pending', 'cancelled').
- **startTime** (string) - Optional - Filters bookings that start after this ISO 8601 timestamp.
- **endTime** (string) - Optional - Filters bookings that end before this ISO 8601 timestamp.

### Response
#### Success Response (200)
- **bookings** (array) - A list of booking objects.
  - **id** (number) - The unique identifier for the booking.
  - **uid** (string) - The unique identifier for the booking.
  - **title** (string) - The title of the booking.
  - **description** (string) - The description of the booking.
  - **hosts** (array) - A list of booking hosts.
  - **status** (string) - The status of the booking (e.g., 'accepted', 'pending', 'cancelled').
  - **cancellationReason** (string) - The reason for cancellation, if applicable.
  - **cancelledByEmail** (string) - The email of the user who cancelled the booking, if applicable.
  - **reschedulingReason** (string) - The reason for rescheduling, if applicable.
  - **rescheduledByEmail** (string) - The email of the user who rescheduled the booking, if applicable.
  - **rescheduledFromUid** (string) - The UID of the previous booking from which this booking was rescheduled.
  - **rescheduledToUid** (string) - The UID of the new booking to which this booking was rescheduled.
  - **start** (string) - The start time of the booking in ISO 8601 format.
  - **end** (string) - The end time of the booking in ISO 8601 format.
  - **duration** (number) - The duration of the booking in minutes.
  - **eventTypeId** (number) - Deprecated. Use `eventType.id` instead.
  - **eventType** (object) - Information about the event type.
    - **id** (number) - The ID of the event type.
    - **name** (string) - The name of the event type.
    - **color** (string) - The color associated with the event type.
  - **meetingUrl** (string) - Deprecated. Use `location` instead.
  - **location** (string) - The location or meeting URL for the booking.
  - **absentHost** (boolean) - Indicates if the host was absent.
  - **createdAt** (string) - The creation timestamp of the booking in ISO 8601 format.
  - **updatedAt** (string) - The last update timestamp of the booking in ISO 8601 format.
  - **metadata** (object) - Additional metadata for the booking.
  - **rating** (number) - The rating of the booking, if provided.
  - **icsUid** (string) - The UID of the ICS event.
  - **attendees** (array) - A list of attendees for the booking.
  - **guests** (array) - A list of guest email addresses for the booking.
  - **bookingFieldsResponses** (object) - User responses to custom booking fields.

#### Response Example
```json
{
  "bookings": [
    {
      "id": 123,
      "uid": "booking_uid_123",
      "title": "Consultation",
      "description": "Learn how to integrate scheduling into marketplace.",
      "hosts": [
        {
          "email": "host@example.com",
          "firstName": "Host",
          "lastName": "User"
        }
      ],
      "status": "accepted",
      "cancellationReason": null,
      "cancelledByEmail": null,
      "reschedulingReason": null,
      "rescheduledByEmail": null,
      "rescheduledFromUid": null,
      "rescheduledToUid": null,
      "start": "2024-08-13T15:30:00Z",
      "end": "2024-08-13T16:30:00Z",
      "duration": 60,
      "eventTypeId": 50,
      "eventType": {
        "id": 50,
        "name": "1-on-1 Meeting",
        "color": "#007bff"
      },
      "meetingUrl": null,
      "location": "https://example.com/meeting/123",
      "absentHost": false,
      "createdAt": "2024-08-13T15:00:00Z",
      "updatedAt": "2024-08-13T15:05:00Z",
      "metadata": {},
      "rating": null,
      "icsUid": "ics_uid_abc",
      "attendees": [
        {
          "email": "attendee@example.com",
          "firstName": "Attendee",
          "lastName": "User"
        }
      ],
      "guests": [],
      "bookingFieldsResponses": {
        "customField": "customValue"
      }
    }
  ]
}
```
```

--------------------------------

### Get busy times

Source: https://cal.com/docs/llms.txt

Retrieves busy times from a calendar. Note: `loggedInUsersTz` is deprecated, use `timeZone` instead. Example request URL: `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`

```APIDOC
## GET /v2/calendars/busy-times

### Description
Get busy times from a calendar.

### Method
GET

### Endpoint
/v2/calendars/busy-times

### Parameters
#### Query Parameters
- **timeZone** (string) - Required - The time zone for the date range.
- **dateFrom** (string) - Required - The start date for the range (YYYY-MM-DD).
- **dateTo** (string) - Required - The end date for the range (YYYY-MM-DD).
- **calendarsToLoad** (array) - Required - An array of calendars to load, each with `credentialId` and `externalId`.
  - **credentialId** (string) - Required - The ID of the calendar credential.
  - **externalId** (string) - Required - The external ID of the calendar.

### Response
#### Success Response (200)
- **busyTimes** (array) - A list of busy time slots.
```

--------------------------------

### Create a New App with Yarn

Source: https://cal.com/docs/developing/guides/appstore-and-integration/build-an-app

Use this command to initiate the creation of a new app. It scaffolds a new directory under `packages/app-store/` and prompts for necessary inputs.

```bash
yarn create-app
```

--------------------------------

### v1 response format example

Source: https://cal.com/docs/api-reference/v2/v1-v2-differences

An example of the response structure used in v1 API.

```JSON
{
  "booking": {...}
}
```

--------------------------------

### Install Yarn Package Manager

Source: https://cal.com/docs/developing/open-source-contribution/introduction

Installs Yarn globally. This is a prerequisite for managing project dependencies.

```bash
npm install -g yarn
```

--------------------------------

### Configure Database URL Environment Variable

Source: https://cal.com/docs/developing/local-development

Set the DATABASE_URL in your .env file to connect to your PostgreSQL database. Replace placeholders with your actual credentials.

```bash
DATABASE_URL='postgresql://<user>:<pass>@<db-host>:<db-port>'
```

--------------------------------

### v1 error handling example

Source: https://cal.com/docs/api-reference/v2/v1-v2-differences

An example of the error response format used in v1 API.

```JSON
{
  "message": "Event type not found"
}
```

--------------------------------

### Example Okta Well-Known URL

Source: https://cal.com/docs/developing/guides/auth-and-provision/how-to-setup-oidc-with-okta

An example of a Well Known URL for Okta, using a sample domain `dev-123456.okta.com`.

```text
https://dev-123456.okta.com/.well-known/openid-configuration
```

--------------------------------

### Install Playwright Browsers

Source: https://cal.com/docs/developing/open-source-contribution/contributors-guide

Run this command to download the required browsers for Playwright E2E tests if they are missing. This resolves 'Executable doesn't exist' errors.

```bash
npx playwright install
```

--------------------------------

### Install Cal.com Atoms with pnpm

Source: https://cal.com/docs/platform/quickstart

Install the atoms package using pnpm. This package provides customizable UI components for scheduling.

```bash
pnpm add @calcom/atoms
```

--------------------------------

### CalProvider Component Setup

Source: https://cal.com/docs/platform/atoms/cal-provider

This snippet demonstrates how to set up the CalProvider component in your application's root file (e.g., _app.js, _app.tsx, App.js, App.ts).

```APIDOC
## CalProvider Component Setup

### Description
This section details the setup and usage of the `CalProvider` component, which is essential for integrating Cal.com scheduling functionalities into your application. It should be placed at the root of your application.

### Method
Component Setup

### Endpoint
N/A (Component Integration)

### Parameters
#### Props
- **clientId** (string) - Required - Your OAuth client ID.
- **options** (object) - Required - Configuration options including:
  - **apiUrl** (string) - Optional - The API endpoint URL. Defaults to "https://api.cal.com/v2".
  - **refreshUrl** (string) - Optional - The URL of an endpoint you build to receive expired access tokens and return new ones. See [Cal.com documentation](https://cal.com/docs/platform/quickstart#4-backend%3A-setting-up-a-refresh-token-endpoint) for setup instructions.
  - **readingDirection** (string) - Optional - Defaults to "ltr". Can be set to "rtl" to change the direction of UI components.
- **accessToken** (string) - Optional - The access token for your managed user, used by Cal.com for scheduling.
- **autoUpdateTimezone** (boolean) - Optional - Whether to automatically update the managed user's timezone. Defaults to `true`.
- **language** (string) - Optional - Language code for the UI. Defaults to "en". Available languages: "en", "de", "fr", "it", "nl", "pt-BR", "es".
- **organizationId** (string) - Optional - The ID of your organization.

### Request Example
```javascript
import "@calcom/atoms/globals.min.css";
import { CalProvider } from '@calcom/atoms';

function MyApp({ Component, pageProps }) {
  const accessToken = "managed-user-access-token";

  return (
    <CalProvider
      clientId={process.env.CAL_OAUTH_CLIENT_ID ?? ""}
      options={{
        apiUrl: process.env.CAL_API_URL ?? "https://api.cal.com/v2",
        refreshUrl: process.env.REFRESH_URL
      }}
      accessToken={accessToken}
    >
      <Component {...pageProps} />
    </CalProvider>
  );
}

export default MyApp;
```

### Response
N/A (Component Integration)

### Error Handling
This component does not have explicit error responses documented in this context. Ensure correct prop values and environment variables are set.
```

--------------------------------

### v2 response format example

Source: https://cal.com/docs/api-reference/v2/v1-v2-differences

An example of the consistent response structure used in v2 API, including status and data fields.

```JSON
{
  "status": "success",
  "data": {...}
}
```