# Calendar API

The Calendar API provides a unified interface across Google Calendar and Microsoft Calendar (Outlook). Events from all connected providers are fetched, normalized to a common format, and sorted by start time. Event data is cached in the calendar_events table for faster access. Requires active OAuth connections to Google and/or Microsoft.

> **Base path:** `/api/v2/calendar` | **Auth:** JWT | **Providers:** Google Calendar, Microsoft Outlook

## GET /api/v2/calendar/events

List Events -- Fetches events from all connected calendar providers (Google Calendar API and Microsoft Graph API), normalizes them to a unified format, sorts by start time, and caches results in the calendar_events table.

**Authentication required**

### Query Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| start | string | No | Current time | ISO 8601 start of the time range. |
| end | string | No | Now + 30 days | ISO 8601 end of the time range. |
| maxResults | number | No | 50 | Maximum number of events per provider. |

### Example Request

```bash
curl -X GET "https://api.lvng.ai/api/v2/calendar/events?start=2026-03-17T00:00:00Z&end=2026-04-17T00:00:00Z&maxResults=25" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200)

```json
{
  "success": true,
  "events": [
    {
      "id": "abc123def456",
      "provider": "google",
      "title": "Sprint 14 Planning",
      "description": "Review backlog and assign tasks for the upcoming sprint.",
      "startTime": "2026-03-17T10:00:00-04:00",
      "endTime": "2026-03-17T11:00:00-04:00",
      "allDay": false,
      "location": "Conference Room B",
      "meetingUrl": "https://meet.google.com/abc-defg-hij",
      "organizerEmail": "matty@lvng.ai",
      "organizerName": "Matty Squarzoni",
      "attendees": [
        { "email": "matty@lvng.ai", "name": "Matty Squarzoni", "status": "accepted" },
        { "email": "alex@lvng.ai", "name": "Alex Rivera", "status": "tentative" }
      ],
      "status": "confirmed",
      "htmlLink": "https://calendar.google.com/calendar/event?eid=abc123",
      "created": "2026-03-10T14:00:00.000Z",
      "updated": "2026-03-10T14:00:00.000Z"
    },
    {
      "id": "AAMkADk3NzQ5...",
      "provider": "microsoft",
      "title": "Design Review",
      "description": "Review new canvas component designs and gather feedback.",
      "startTime": "2026-03-19T14:00:00Z",
      "endTime": "2026-03-19T14:45:00Z",
      "allDay": false,
      "location": "",
      "meetingUrl": "https://teams.microsoft.com/l/meetup-join/abc123",
      "organizerEmail": "jordan@lvng.ai",
      "organizerName": "Jordan Lee",
      "attendees": [
        { "email": "jordan@lvng.ai", "name": "Jordan Lee", "status": "organizer" },
        { "email": "matty@lvng.ai", "name": "Matty Squarzoni", "status": "accepted" }
      ],
      "status": "busy",
      "htmlLink": "https://outlook.office365.com/owa/?itemid=AAMkADk3...",
      "created": "2026-03-15T09:00:00.000Z",
      "updated": "2026-03-15T09:00:00.000Z"
    }
  ],
  "count": 2
}
```

## GET /api/v2/calendar/events/:id

Get Event -- Returns a single calendar event by its provider-specific ID. Defaults to Google Calendar; pass provider=microsoft for Outlook events.

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | The provider-specific event ID (Google event ID or Microsoft Graph event ID). |

### Query Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| provider | string | No | google | Calendar provider: google or microsoft. |

### Example Request

```bash
curl -X GET "https://api.lvng.ai/api/v2/calendar/events/abc123def456?provider=google" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200)

```json
{
  "success": true,
  "event": {
    "id": "abc123def456",
    "provider": "google",
    "title": "Sprint 14 Planning",
    "description": "Review backlog and assign tasks for the upcoming sprint.",
    "startTime": "2026-03-17T10:00:00-04:00",
    "endTime": "2026-03-17T11:00:00-04:00",
    "allDay": false,
    "location": "Conference Room B",
    "meetingUrl": "https://meet.google.com/abc-defg-hij",
    "organizerEmail": "matty@lvng.ai",
    "organizerName": "Matty Squarzoni",
    "attendees": [
      { "email": "matty@lvng.ai", "name": "Matty Squarzoni", "status": "accepted" },
      { "email": "alex@lvng.ai", "name": "Alex Rivera", "status": "tentative" }
    ],
    "status": "confirmed",
    "htmlLink": "https://calendar.google.com/calendar/event?eid=abc123",
    "created": "2026-03-10T14:00:00.000Z",
    "updated": "2026-03-10T14:00:00.000Z"
  }
}
```

## POST /api/v2/calendar/events

Create Event -- Creates a new event on the specified provider's calendar. Google events send attendee notifications automatically via sendUpdates: all. Microsoft events are created with UTC time zone.

**Authentication required**

### Body Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| provider | string | No | google | Calendar provider: google or microsoft. |
| title | string | Yes | -- | Event title (maps to summary for Google, subject for Microsoft). |
| description | string | No | -- | Event description. |
| startTime | string | Yes | -- | Event start time in ISO 8601 format. |
| endTime | string | Yes | -- | Event end time in ISO 8601 format. |
| location | string | No | -- | Physical address or meeting URL. |
| attendees | object[] | No | -- | Array of attendee objects with email and name fields. |

### Example Request

```bash
curl -X POST https://api.lvng.ai/api/v2/calendar/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "title": "Product Demo",
    "description": "Demo the new voice notes feature to the team.",
    "startTime": "2026-03-21T15:00:00Z",
    "endTime": "2026-03-21T15:30:00Z",
    "location": "https://meet.google.com/xyz-abcd-efg",
    "attendees": [
      { "email": "alex@lvng.ai", "name": "Alex Rivera" },
      { "email": "jordan@lvng.ai", "name": "Jordan Lee" }
    ]
  }'
```

### Response (200)

```json
{
  "success": true,
  "event": {
    "id": "ghi789jkl012",
    "provider": "google",
    "title": "Product Demo",
    "description": "Demo the new voice notes feature to the team.",
    "startTime": "2026-03-21T15:00:00Z",
    "endTime": "2026-03-21T15:30:00Z",
    "allDay": false,
    "location": "https://meet.google.com/xyz-abcd-efg",
    "meetingUrl": "",
    "organizerEmail": "matty@lvng.ai",
    "organizerName": "Matty Squarzoni",
    "attendees": [
      { "email": "matty@lvng.ai", "name": "Matty Squarzoni", "status": "accepted" },
      { "email": "alex@lvng.ai", "name": "Alex Rivera", "status": "needsAction" },
      { "email": "jordan@lvng.ai", "name": "Jordan Lee", "status": "needsAction" }
    ],
    "status": "confirmed",
    "htmlLink": "https://calendar.google.com/calendar/event?eid=ghi789",
    "created": "2026-03-19T11:00:00.000Z",
    "updated": "2026-03-19T11:00:00.000Z"
  }
}
```

## PATCH /api/v2/calendar/events/:id

Update Event -- Partially updates an existing calendar event. Only included fields are modified. Uses Google Calendar patch or Microsoft Graph PATCH depending on provider.

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | The provider-specific event ID. |

### Body Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| provider | string | No | google | Calendar provider: google or microsoft. |
| title | string | No | -- | Updated event title. |
| description | string | No | -- | Updated description. |
| startTime | string | No | -- | Updated start time (ISO 8601). |
| endTime | string | No | -- | Updated end time (ISO 8601). |
| location | string | No | -- | Updated location. |

### Example Request

```bash
curl -X PATCH https://api.lvng.ai/api/v2/calendar/events/ghi789jkl012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "google",
    "startTime": "2026-03-21T16:00:00Z",
    "endTime": "2026-03-21T16:30:00Z"
  }'
```

### Response (200)

```json
{
  "success": true,
  "event": {
    "id": "ghi789jkl012",
    "provider": "google",
    "title": "Product Demo",
    "description": "Demo the new voice notes feature to the team.",
    "startTime": "2026-03-21T16:00:00Z",
    "endTime": "2026-03-21T16:30:00Z",
    "allDay": false,
    "location": "https://meet.google.com/xyz-abcd-efg",
    "meetingUrl": "",
    "organizerEmail": "matty@lvng.ai",
    "organizerName": "Matty Squarzoni",
    "attendees": [
      { "email": "matty@lvng.ai", "name": "Matty Squarzoni", "status": "accepted" },
      { "email": "alex@lvng.ai", "name": "Alex Rivera", "status": "needsAction" }
    ],
    "status": "confirmed",
    "htmlLink": "https://calendar.google.com/calendar/event?eid=ghi789",
    "created": "2026-03-19T11:00:00.000Z",
    "updated": "2026-03-19T11:20:00.000Z"
  }
}
```

## DELETE /api/v2/calendar/events/:id

Delete Event -- Deletes a calendar event from the provider. Uses Google Calendar delete or Microsoft Graph DELETE depending on the provider query parameter.

**Authentication required**

### Path Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | The provider-specific event ID to delete. |

### Query Parameters

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| provider | string | No | google | Calendar provider: google or microsoft. |

### Example Request

```bash
curl -X DELETE "https://api.lvng.ai/api/v2/calendar/events/ghi789jkl012?provider=google" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200)

```json
{
  "success": true,
  "message": "Event deleted"
}
```

## GET /api/v2/calendar/availability

Check Availability -- Returns busy time slots within the specified range by querying the Google Calendar free/busy API for all connected accounts. Useful for scheduling and finding open time windows.

**Authentication required**

### Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| start | string | Yes | ISO 8601 start of the availability window. |
| end | string | Yes | ISO 8601 end of the availability window. |

### Example Request

```bash
curl -X GET "https://api.lvng.ai/api/v2/calendar/availability?start=2026-03-20T09:00:00Z&end=2026-03-20T17:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response (200)

```json
{
  "success": true,
  "busy": [
    {
      "start": "2026-03-20T10:00:00Z",
      "end": "2026-03-20T11:00:00Z",
      "provider": "google"
    },
    {
      "start": "2026-03-20T13:00:00Z",
      "end": "2026-03-20T14:00:00Z",
      "provider": "google"
    }
  ]
}
```