API Reference

Authentication

ScholarCal uses Supabase Auth. Browser clients authenticate via session cookies (set automatically after OAuth sign-in). Server-to-server clients should pass an API key as a Bearer token.

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.scholarcal.com/api/events

Events

POST /api/events/create

Create a new event with conflict checking.

curl -X POST /api/events/create \
  -H "Content-Type: application/json" \
  -d '{"title":"Team standup","start_time":"2026-03-01T09:00:00Z","end_time":"2026-03-01T09:30:00Z"}'

PATCH /api/events

Update an existing event. Pass the event id plus any fields to update.

DELETE /api/events?id=UUID

Delete an event by ID.

AI Scheduling

POST /api/assistant/schedule

Send a natural language message to the AI assistant. Returns a proposed event, study plan, email draft, or direct confirmation depending on intent.

curl -X POST /api/assistant/schedule \
  -H "Content-Type: application/json" \
  -d '{"message":"Schedule a study session for calc tomorrow 3-5pm","history":[]}'

POST /api/assistant/confirm

Confirm a proposed event from the schedule endpoint. Performs conflict checking and writes to the database.

Unified Events

GET /api/unified/events

Fetch events from all sources (local, Google, Microsoft, Canvas) with filtering.

POST /api/unified/sync

Trigger a sync for a specific provider (canvas, google, or microsoft).

Settings

GET /api/settings

Retrieve current user settings. Creates defaults on first call.

PATCH /api/settings

Update user settings. Accepts any subset of settings fields.

Mail

POST /api/mail/send

Send an email via Gmail or Outlook. Requires the appropriate OAuth scope.

Calendar Feed

GET /api/calendar/ical?token=FEED_TOKEN

Export your events as an iCal feed. The feed token is generated in Settings. No authentication required — the token acts as the credential.

POST /api/calendar/import

Import events from an .ics file. Accepts multipart form data or raw text/calendar body.