Calendar API

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

All calendar endpoints require an authenticated session. The user is identified from the session automatically — you do not pass a userId parameter.

Most calendar endpoints also 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

Authentication

All calendar endpoints require a valid NextAuth session. Requests without an active session receive a 401 Unauthorized response (or a redirect to /login for browser-based flows). The authenticated user’s identity is derived from the session. You do not need to include a userId parameter in any request.

Token storage

Calendar tokens (access and refresh tokens) are encrypted at rest using AES-256-GCM before being persisted to the database. Tokens are never stored in plaintext.

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`

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
401	Not authenticated (no active session)
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	HMAC-signed state token generated during the connect flow. Contains the user ID and a timestamp, verified on callback. Expires after 10 minutes.
`error`	string	Error code if the user denied access or an error occurred

Behavior

On success, this endpoint:

Verifies the HMAC-signed state parameter and checks it has not expired.
Exchanges the authorization code for access and refresh tokens.
Retrieves the user’s primary calendar ID and timezone.
Encrypts and persists the tokens to the database (AES-256-GCM).
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. Requires an active session. If the user is not authenticated, this endpoint redirects to /login.

Query parameters

Parameter	Type	Required	Description
`action`	string	Yes	Must be `auth`

List events

GET /api/calendar?action=list

Returns calendar events within a date range. The user is identified from the session.

Query parameters

Parameter	Type	Required	Description
`action`	string	Yes	Must be `list`
`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	Not authenticated or calendar not connected

Check availability

GET /api/calendar?action=availability

Returns available and busy time slots for a given date. Slots are one hour each, from 09:00 to 23:00. The user is identified from the session.

Query parameters

Parameter	Type	Required	Description
`action`	string	Yes	Must be `availability`
`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	Not authenticated or calendar not connected

Create event

POST /api/calendar

Creates a new calendar event. The user is identified from the session.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `create-event`
`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",
  "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	Not authenticated or calendar not connected
500	Internal error

Update event

POST /api/calendar

Updates an existing calendar event. Only the fields you include are changed. The user is identified from the session.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `update-event`
`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	Not authenticated or calendar not connected
500	Internal error

Delete event

POST /api/calendar

Deletes a calendar event. The user is identified from the session.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `delete-event`
`eventId`	string	Yes	ID of the event to delete

Response

{
  "success": true
}

Errors

Code	Description
401	Not authenticated or 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. The user is identified from the session.

Request body

Field	Type	Required	Description
`action`	string	Yes	Must be `quick-add`
`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	Not authenticated or calendar not connected
500	Internal error

​Calendar API

​Base URL

​Authentication

​Token storage

​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

Authentication

Token storage

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