Skip to main content
GET
/
calendar
/
events
Get Events
curl --request GET \
  --url https://api.example.com/calendar/events
{
  "events": [
    {
      "id": "<string>",
      "google_event_id": "<string>",
      "calendar_id": "<string>",
      "summary": "<string>",
      "description": "<string>",
      "location": "<string>",
      "start": {},
      "end": {},
      "status": "<string>",
      "color": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>"
    }
  ],
  "masters": [
    {
      "recurrence": [
        {}
      ]
    }
  ],
  "exceptions": [
    {
      "recurring_event_id": "<string>",
      "original_start_time": {}
    }
  ]
}

​
Endpoint

GET /calendar/events
Retrieves calendar events from the local encrypted database. Events are decrypted using the user’s encryption key before being returned. This endpoint returns cached events and does not sync with Google Calendar.

​
Authentication

Requires a valid authentication token in the request headers.

​
Query Parameters

​
calendar_ids
string
Optional comma-separated list of calendar IDs to filter events. If not provided, returns events from all user’s calendars.Maximum 20 calendar IDs per request.Example: cal_abc123,cal_def456

​
Response

Returns three arrays of events categorized by type:
​
events
array
required
Regular (non-recurring) calendar events
​
masters
array
required
Master events for recurring series. These define the recurrence pattern but don’t represent individual instances.
​
exceptions
array
required
Exception events - modified or cancelled instances of recurring events

​
Decryption Process

  1. Events are stored encrypted in the database
  2. User’s encryption key is derived from their user ID
  3. Events are decrypted in parallel using thread pool (up to 8 workers)
  4. Decrypted events include sensitive fields: summary, description, location

​
Example Request

cURL
curl -X GET "https://api.chronoscalendar.com/calendar/events?calendar_ids=cal_abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
All Calendars
curl -X GET "https://api.chronoscalendar.com/calendar/events" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Example Response

{
  "events": [
    {
      "id": "evt_123",
      "google_event_id": "abc123xyz",
      "calendar_id": "cal_abc123",
      "summary": "Team Meeting",
      "description": "Discuss Q2 roadmap",
      "location": "Conference Room A",
      "start": {
        "dateTime": "2026-03-05T14:00:00Z",
        "timeZone": "America/New_York"
      },
      "end": {
        "dateTime": "2026-03-05T15:00:00Z",
        "timeZone": "America/New_York"
      },
      "status": "confirmed",
      "color": "#9fe1e7",
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-03-02T12:30:00Z"
    }
  ],
  "masters": [
    {
      "id": "evt_456",
      "google_event_id": "def456uvw",
      "calendar_id": "cal_abc123",
      "summary": "Weekly Standup",
      "start": {
        "dateTime": "2026-03-03T09:00:00Z",
        "timeZone": "America/New_York"
      },
      "end": {
        "dateTime": "2026-03-03T09:30:00Z",
        "timeZone": "America/New_York"
      },
      "recurrence": [
        "RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"
      ],
      "status": "confirmed"
    }
  ],
  "exceptions": [
    {
      "id": "evt_789",
      "google_event_id": "ghi789rst_20260305T090000Z",
      "calendar_id": "cal_abc123",
      "recurring_event_id": "ghi789rst",
      "original_start_time": {
        "dateTime": "2026-03-05T09:00:00Z"
      },
      "summary": "Weekly Standup - CANCELLED",
      "status": "cancelled"
    }
  ]
}

​
Empty Response

If no events are found or no calendars are specified: 
{
  "events": [],
  "masters": [],
  "exceptions": []
}

​
Performance Considerations

  • Parallel Decryption: Events are decrypted concurrently using ThreadPoolExecutor
  • Worker Threads: Up to 8 workers (based on CPU count)
  • Database Queries: Optimized with separate queries for events, masters, and exceptions
  • Filtered by Status: Automatically excludes cancelled regular events

​
Error Responses

​
400 Bad Request
Invalid calendar_ids parameter (more than 20 calendars)
​
401 Unauthorized
Authentication token is missing or invalid
​
500 Internal Server Error
Decryption failed or database error occurred

​
Use Cases

  • Initial Load: Fetch cached events on app startup
  • Offline Access: Access events without Google Calendar connection
  • Quick Retrieval: Get events faster than syncing from Google
  • Calendar Filtering: View events from specific calendars only

​
Source Code Reference

See implementation in:
  • backend/app/routers/calendar.py:67-102 (endpoint handler)
  • backend/app/calendar/db.py:257-295 (database queries)
  • backend/app/calendar/helpers.py (decryption logic)

Build docs developers (and LLMs) love

Get started for freeTalk to us