---
title: "List the authenticated user's calendar events"
method: GET
path: "/api/calendar-events"
tags: ["Calendar"]
---

# List the authenticated user's calendar events

`GET /api/calendar-events`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/calendar-events`
- Auth: none declared

Return the user's active calendar events, anchor-date ascending.

`start`/`end` (both ISO 'YYYY-MM-DD') optionally window the result on
the anchor date; recurring events whose series could still touch the
window are included (the P4 reader expands occurrences). Bad date
formats are ignored (treated as no-window) rather than 400 — a list
GET should degrade gracefully.

Required fields (silent-shadow contract): `events: []`, `count: 0`
even on the error path so the frontend `.forEach` never NPEs.

## Query parameters

- `start` string, nullable: Window start date 'YYYY-MM-DD'.
- `end` string, nullable: Window end date 'YYYY-MM-DD'.

## Response `200`

Successful Response

- CalendarEventsListResponse: `GET /api/calendar-events` response. Frontend iterates `data.events.forEach(...)`; both fields REQUIRED so a missing one NPEs the calendar render (silent-shadow class).
  - `events` UserCalendarEvent[], required: User's active events, anchor-date ascending.
    - `id` integer, required: Primary key.
    - `user_id` integer, required: Owning user's id.
    - `title` string, required: Event title (<=120 chars).
    - `note` string, nullable: Optional free-text note.
    - `ticker` string, nullable: Optional associated ticker (uppercased).
    - `event_date` string, required: Anchor occurrence date, ISO 'YYYY-MM-DD'.
    - `event_time` string, nullable: Optional time-of-day 'HH:MM:SS'; null = all-day.
    - `recurrence` string, required: One of none|daily|weekly|monthly|yearly.
    - `recurrence_until` string, nullable: Recurrence end date 'YYYY-MM-DD'; null = open-ended.
    - `remind_offset_minutes` integer, nullable: Minutes-before-occurrence to remind (0 = day-of, 1440 = 1 day before); null = no reminder.
    - `status` string, required: One of active|cancelled.
    - `last_reminded_for` string, nullable: Occurrence-date a reminder last fired (dedupe).
    - `created_at` string, required: ISO-8601 timestamp.
    - `updated_at` string, required: ISO-8601 timestamp.
  - `count` integer, required: len(events).

## Other responses

- `401`: Unauthorized
- `422`: Validation Error
- `500`: Internal Server Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)