Calendar

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

List Events

GET/api/v2/calendar/eventsAuthenticated

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.

Query Parameters

startstring

Default: Current time

ISO 8601 start of the time range.

endstring

Default: Now + 30 days

ISO 8601 end of the time range.

maxResultsnumber

Default: 50

Maximum number of events per provider.

Request

cURL

400">curl -X 400">GET 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/calendar/events?start=2026-03-17T00:00:00Z&end=2026-04-17T00:00:00Z&maxResults=25" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

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

Get Event

GET/api/v2/calendar/events/:idAuthenticated

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

Path Parameters

idstringrequired

The provider-specific event ID (Google event ID or Microsoft Graph event ID).

Query Parameters

providerstring

Default: google

Calendar provider: google or microsoft.

Request

cURL

400">curl -X 400">GET 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/calendar/events/abc123def456?provider=google" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

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

Create Event

POST/api/v2/calendar/eventsAuthenticated

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.

Body Parameters

providerstring

Default: google

Calendar provider: google or microsoft.

titlestringrequired

Event title (maps to summary for Google, subject for Microsoft).

descriptionstring

Event description.

startTimestringrequired

Event start time in ISO 8601 format.

endTimestringrequired

Event end time in ISO 8601 format.

locationstring

Physical address or meeting URL.

attendeesobject[]

Array of attendee objects with email and name fields.

Request

cURL

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

Response 200

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

Update Event

PATCH/api/v2/calendar/events/:idAuthenticated

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

Path Parameters

idstringrequired

The provider-specific event ID.

Body Parameters

providerstring

Default: google

Calendar provider: google or microsoft.

titlestring

Updated event title.

descriptionstring

Updated description.

startTimestring

Updated start time (ISO 8601).

endTimestring

Updated end time (ISO 8601).

locationstring

Updated location.

Request

cURL

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

Response 200

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

Delete Event

DELETE/api/v2/calendar/events/:idAuthenticated

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

Path Parameters

idstringrequired

The provider-specific event ID to delete.

Query Parameters

providerstring

Default: google

Calendar provider: google or microsoft.

Request

cURL

400">curl -X 400">DELETE 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/calendar/events/ghi789jkl012?provider=google" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"message": 400">class="text-emerald-400">"Event deleted"
}

Check Availability

GET/api/v2/calendar/availabilityAuthenticated

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.

Query Parameters

startstringrequired

ISO 8601 start of the availability window.

endstringrequired

ISO 8601 end of the availability window.

Request

cURL

400">curl -X 400">GET 400">class="text-emerald-400">"https:400">class="text-zinc-500">//api.lvng.ai/api/v2/calendar/availability?start=2026-03-20T09:00:00Z&end=2026-03-20T17:00:00Z" \
  -H 400">class="text-emerald-400">"Authorization: Bearer YOUR_API_KEY"

Response 200

{
  400">class="text-emerald-400">"success": true,
  400">class="text-emerald-400">"busy": [
    {
      400">class="text-emerald-400">"start": 400">class="text-emerald-400">"2026-03-20T10:00:00Z",
      400">class="text-emerald-400">"end": 400">class="text-emerald-400">"2026-03-20T11:00:00Z",
      400">class="text-emerald-400">"provider": 400">class="text-emerald-400">"google"
    },
    {
      400">class="text-emerald-400">"start": 400">class="text-emerald-400">"2026-03-20T13:00:00Z",
      400">class="text-emerald-400">"end": 400">class="text-emerald-400">"2026-03-20T14:00:00Z",
      400">class="text-emerald-400">"provider": 400">class="text-emerald-400">"google"
    }
  ]
}