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:

Exchanges the authorization code for access and refresh tokens.
Retrieves the user’s primary calendar ID and timezone.
Stores the connection for future API calls.
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": ["promoter@example.com"]
}

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

Getting Started

Core Concepts

Integrations

Core Services

Payments

API Reference

MCP

Security

​Calendar API

​Base URL

​Connect calendar

​Request body

​Response

​Errors

​OAuth callback

​Query parameters

​Behavior

​Error redirects

​Start OAuth (redirect)

​Query parameters

​List events

​Query parameters

​Response

​Errors

​Check availability

​Query parameters

​Response

​Errors

​Create event

​Request body

​Example request

​Response

​Errors

​Update event

​Request body

​Response

​Errors

​Delete event

​Request body

​Response

​Errors

​Quick add

​Request body

​Response

​Errors

Calendar API

Base URL

Connect calendar

Request body

Response

Errors

OAuth callback

Query parameters

Behavior

Error redirects

Start OAuth (redirect)

Query parameters

List events

Query parameters

Response

Errors

Check availability

Query parameters

Response

Errors

Create event

Request body

Example request

Response

Errors

Update event

Request body

Response

Errors

Delete event

Request body

Response

Errors

Quick add

Request body

Response

Errors