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

# Platform API Introduction

> Build powerful scheduling integrations with Cal.com's Platform API v2

The Cal.com Platform API v2 provides a comprehensive REST API for building scheduling applications and integrations. It enables you to programmatically manage bookings, event types, users, webhooks, and more.

## Base URL

All API requests should be made to:

```
https://api.cal.com/v2
```

## API Versioning

The Platform API uses date-based versioning to ensure backward compatibility. Current supported versions:

* **2024-08-13** - Latest version with enhanced booking features
* **2024-06-14** - Extended booking management
* **2024-06-11** - Additional booking endpoints
* **2024-04-15** - Core booking API

Specify the API version using the `cal-api-version` header:

```bash theme={null}
curl -X GET https://api.cal.com/v2/bookings \
  -H "Authorization: Bearer cal_live_<your_api_key>" \
  -H "cal-api-version: 2024-08-13"
```

## Core Features

<CardGroup cols={2}>
  <Card title="Bookings Management" icon="calendar-check">
    Create, retrieve, update, and cancel bookings programmatically
  </Card>

  <Card title="Event Types" icon="calendar">
    Manage event types with custom availability and settings
  </Card>

  <Card title="Webhooks" icon="webhook">
    Receive real-time notifications for booking events
  </Card>

  <Card title="OAuth 2.0" icon="shield-check">
    Secure authentication for third-party applications
  </Card>
</CardGroup>

## Key Endpoints

### Bookings

```bash theme={null}
GET    /v2/bookings              # List bookings
GET    /v2/bookings/:bookingUid  # Get booking details
POST   /v2/bookings              # Create a booking
POST   /v2/bookings/:bookingUid/cancel  # Cancel booking
POST   /v2/bookings/recurring    # Create recurring booking
```

### Event Types

```bash theme={null}
GET    /v2/event-types           # List event types
GET    /v2/event-types/:id       # Get event type
POST   /v2/event-types           # Create event type
PATCH  /v2/event-types/:id       # Update event type
DELETE /v2/event-types/:id       # Delete event type
```

### Webhooks

```bash theme={null}
GET    /v2/webhooks              # List webhooks
POST   /v2/webhooks              # Create webhook
PATCH  /v2/webhooks/:webhookId   # Update webhook
DELETE /v2/webhooks/:webhookId   # Delete webhook
```

## Response Format

All API responses follow a consistent structure:

```json theme={null}
{
  "status": "success",
  "data": {
    // Response data
  }
}
```

### Success Response

```json theme={null}
{
  "status": "success",
  "data": {
    "id": 123,
    "title": "30 Minute Meeting",
    "startTime": "2024-03-15T10:00:00Z"
  }
}
```

### Error Response

```json theme={null}
{
  "status": "error",
  "error": {
    "message": "Booking not found",
    "code": "NOT_FOUND"
  }
}
```

## HTTP Status Codes

| Status Code | Description                                      |
| ----------- | ------------------------------------------------ |
| 200         | Success - Request completed successfully         |
| 201         | Created - Resource created successfully          |
| 400         | Bad Request - Invalid request parameters         |
| 401         | Unauthorized - Invalid or missing authentication |
| 403         | Forbidden - Insufficient permissions             |
| 404         | Not Found - Resource not found                   |
| 429         | Too Many Requests - Rate limit exceeded          |
| 500         | Internal Server Error - Server error             |

## Request Headers

### Required Headers

```bash theme={null}
Authorization: Bearer cal_live_<your_api_key>
Content-Type: application/json
```

### Optional Headers

```bash theme={null}
cal-api-version: 2024-08-13        # API version
X-Cal-Client-ID: <client_id>       # OAuth client ID
X-Request-Id: <unique_id>          # Request tracking ID
```

## Pagination

List endpoints support cursor-based pagination:

```bash theme={null}
GET /v2/bookings?limit=10&cursor=0
```

**Parameters:**

* `limit` - Number of results per page (default: 10, max: 250)
* `cursor` - Pagination cursor (offset)

**Response:**

```json theme={null}
{
  "status": "success",
  "data": {
    "bookings": [...],
    "nextCursor": 10,
    "totalCount": 45
  }
}
```

## Filtering

Many endpoints support filtering:

```bash theme={null}
GET /v2/bookings?filters[status]=upcoming
GET /v2/bookings?filters[eventTypeId]=123
```

## Platform Features

### Managed Users

Create and manage users programmatically:

```bash theme={null}
POST /v2/organizations/:orgId/users
```

### Team Management

```bash theme={null}
GET  /v2/teams
POST /v2/teams/:teamId/memberships
```

### OAuth Clients

```bash theme={null}
GET /v2/oauth-clients
```

## SDK Libraries

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { CalComAPI } from '@calcom/api-client';

  const cal = new CalComAPI({
    apiKey: 'cal_live_xxxxx'
  });

  const booking = await cal.bookings.create({
    eventTypeId: 123,
    start: '2024-03-15T10:00:00Z',
    responses: {
      name: 'John Doe',
      email: 'john@example.com'
    }
  });
  ```

  ```python Python theme={null}
  from calcom import CalComAPI

  cal = CalComAPI(api_key='cal_live_xxxxx')

  booking = cal.bookings.create(
      event_type_id=123,
      start='2024-03-15T10:00:00Z',
      responses={
          'name': 'John Doe',
          'email': 'john@example.com'
      }
  )
  ```
</CodeGroup>

## Getting Started

<Steps>
  <Step title="Get API Credentials">
    Generate an API key or set up OAuth 2.0 authentication
  </Step>

  <Step title="Make Your First Request">
    Test the API with a simple GET request to list bookings
  </Step>

  <Step title="Set Up Webhooks">
    Configure webhooks to receive real-time event notifications
  </Step>

  <Step title="Build Your Integration">
    Use the full API to build your scheduling application
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn about API keys and OAuth 2.0
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api/webhooks">
    Set up real-time event notifications
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api/rate-limits">
    Understand rate limiting policies
  </Card>

  <Card title="OAuth 2.0 Guide" icon="shield" href="/api/oauth">
    Implement OAuth 2.0 flows
  </Card>
</CardGroup>

## Support

Need help? Here are some resources:

* **API Reference**: Detailed endpoint documentation
* **GitHub**: [github.com/calcom/cal.com](https://github.com/calcom/cal.com)
* **Community**: [cal.com/slack](https://cal.com/slack)
* **Email**: [support@cal.com](mailto:support@cal.com)