Calendar API

Google Calendar integration endpoints for OAuth, event management, and availability checks

Calendar API

Connect a Google Calendar account and manage events, check availability, and schedule directly through the API.

Most calendar endpoints require a connected Google Calendar account. Use the connect flow to authorize access before calling event endpoints.

Base URL

https://agentbot.raveculture.xyz/api/calendar

Connect calendar

POST /api/calendar

Initiates the Google Calendar OAuth flow. Returns an authorization URL that the user must visit to grant calendar access.

Request body

Field	Type	Required	Description
action	string	Yes	Must be connect
userId	string	Yes	Your user identifier

Response

{
  "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?..."
}

Redirect the user to authUrl to begin the OAuth consent flow. After granting access, Google redirects to the callback endpoint below.

Errors

Code	Description
400	Invalid action

OAuth callback

GET /api/calendar/callback

Handles the OAuth authorization code exchange after Google redirects the user back from the consent screen. You do not call this endpoint directly — Google redirects to it automatically.

Query parameters

Parameter	Type	Description
code	string	Authorization code provided by Google
state	string	The userId passed during the connect flow
error	string	Error code if the user denied access or an error occurred

Behavior

On success, this endpoint:

1. Exchanges the authorization code for access and refresh tokens.
2. Retrieves the user’s primary calendar ID and timezone.
3. Stores the connection for future API calls.
4. Redirects to /dashboard/calendar?connected=true.

Error redirects

If an error occurs, the endpoint redirects to /dashboard/calendar with an error query parameter:

Redirect query	Description
error=<google_error>	The user denied access or Google returned an error
error=no_code	No authorization code was present in the callback
error=token_failed	The authorization code could not be exchanged for tokens
error=unknown	An unexpected error occurred during the callback

Start OAuth (redirect)

GET /api/calendar?action=auth

Redirects the browser directly to the Google OAuth consent screen. This is an alternative to the POST-based connect flow — use it when you want a simple link-based authorization.

Query parameters

Parameter	Type	Required	Description
action	string	Yes	Must be auth

List events

GET /api/calendar?action=list&userId={userId}

Returns calendar events within a date range.

Query parameters

Parameter	Type	Required	Description
action	string	Yes	Must be list
userId	string	Yes	Your user identifier
start	string	No	ISO 8601 start date. Defaults to now.
end	string	No	ISO 8601 end date. Defaults to 30 days from now.

Response

{
  "events": [
    {
      "id": "event_abc123",
      "summary": "Team standup",
      "start": { "dateTime": "2026-03-24T10:00:00Z" },
      "end": { "dateTime": "2026-03-24T10:30:00Z" },
      "location": "Zoom"
    }
  ],
  "timezone": "America/New_York"
}

Errors

Code	Description
401	Calendar not connected

Check availability

GET /api/calendar?action=availability&userId={userId}

Returns available and busy time slots for a given date. Slots are one hour each, from 09:00 to 23:00.

Query parameters

Parameter	Type	Required	Description
action	string	Yes	Must be availability
userId	string	Yes	Your user identifier
date	string	No	Date in YYYY-MM-DD format. Defaults to today.

Response

{
  "availableSlots": [
    { "start": "2026-03-24T09:00:00", "end": "2026-03-24T10:00:00" },
    { "start": "2026-03-24T11:00:00", "end": "2026-03-24T12:00:00" }
  ],
  "busySlots": [
    { "start": "2026-03-24T10:00:00Z", "end": "2026-03-24T11:00:00Z" }
  ],
  "date": "2026-03-24"
}

Errors

Code	Description
401	Calendar not connected

Create event

POST /api/calendar

Creates a new calendar event.

Request body

Field	Type	Required	Description
action	string	Yes	Must be create-event
userId	string	Yes	Your user identifier
title	string	Yes	Event title
start	string	Yes	ISO 8601 start time
end	string	Yes	ISO 8601 end time
description	string	No	Event description
location	string	No	Event location
attendees	string[]	No	List of attendee email addresses

Example request

{
  "action": "create-event",
  "userId": "user_123",
  "title": "DJ Set @ Warehouse",
  "start": "2026-03-28T22:00:00Z",
  "end": "2026-03-29T02:00:00Z",
  "location": "Warehouse 42, London",
  "attendees": ["[e-mail]"]
}

Response

{
  "success": true,
  "eventId": "event_abc123",
  "event": {
    "id": "event_abc123",
    "summary": "DJ Set @ Warehouse",
    "start": { "dateTime": "2026-03-28T22:00:00Z" },
    "end": { "dateTime": "2026-03-29T02:00:00Z" }
  }
}

Errors

Code	Description
401	Calendar not connected
500	Internal error

Update event

POST /api/calendar

Updates an existing calendar event. Only the fields you include are changed.

Request body

Field	Type	Required	Description
action	string	Yes	Must be update-event
userId	string	Yes	Your user identifier
eventId	string	Yes	ID of the event to update
title	string	No	Updated event title
description	string	No	Updated description
start	string	No	Updated start time (ISO 8601)
end	string	No	Updated end time (ISO 8601)
location	string	No	Updated location

Response

{
  "success": true,
  "event": { "id": "event_abc123", "summary": "Updated title" }
}

Errors

Code	Description
401	Calendar not connected
500	Internal error

Delete event

POST /api/calendar

Deletes a calendar event.

Request body

Field	Type	Required	Description
action	string	Yes	Must be delete-event
userId	string	Yes	Your user identifier
eventId	string	Yes	ID of the event to delete

Response

{
  "success": true
}

Errors

Code	Description
401	Calendar not connected
500	Internal error

Quick add

POST /api/calendar

Creates an event from a natural language string using Google Calendar’s quick-add feature.

Request body

Field	Type	Required	Description
action	string	Yes	Must be quick-add
userId	string	Yes	Your user identifier
text	string	Yes	Natural language event description (for example, "Meeting with Sarah tomorrow at 3pm")

Response

{
  "success": true,
  "eventId": "event_abc123"
}

Errors

Code	Description
401	Calendar not connected
500	Internal error