# API Surface

> Generated from `.planning/intel/api-map.json`. Do not edit by hand.

## `GET /health`

- **method:** GET
- **path:** /health
- **auth:** none
- **file:** apps/api/src/routes/health.ts
- **description:** DB liveness probe. Returns { ok: true, db: 'up' } or 503.

## `GET /callback`

- **method:** GET
- **path:** /callback
- **auth:** none (OIDC callback — must be before auth guard)
- **file:** apps/api/src/index.ts
- **description:** OIDC authorization-code callback. Processed by @hono/oidc-auth processOAuthCallback.

## `GET /api/login`

- **method:** GET
- **path:** /api/login
- **auth:** oidcAuthMiddleware
- **file:** apps/api/src/index.ts
- **description:** Auth entry point. Redirects to / after successful OIDC login. PWA navigates here for re-auth.

## `GET /api/me`

- **method:** GET
- **path:** /api/me
- **auth:** oidcAuthMiddleware
- **file:** apps/api/src/routes/me.ts
- **response:** { user: { id: number, displayName: string|null, color: string } }
- **description:** Returns authenticated member's identity and assigned color. Upserts user row on first call.

## `GET /api/events`

- **method:** GET
- **path:** /api/events
- **auth:** oidcAuthMiddleware
- **params:** start (YYYY-MM-DD, required), end (YYYY-MM-DD, required)
- **file:** apps/api/src/routes/events.ts
- **response:** { occurrences: CalendarOccurrence[] }
- **description:** Windowed calendar events. Max 90-day window. Reads only from MariaDB cache; never hits Fastmail. Expands RRULEs server-side.

## `POST /api/events/create`

- **method:** POST
- **path:** /api/events/create
- **auth:** oidcAuthMiddleware
- **body:** CreateEventPayload (title, allDay, start, end, recurrence?, location?, description?, calendarUrl?)
- **file:** apps/api/src/routes/events.ts
- **response:** 202 { uid: string }
- **description:** Enqueues create to calendarOutbox. Async CalDAV write-back via outbox worker. Returns uid immediately.

## `PATCH /api/events/:uid/edit`

- **method:** PATCH
- **path:** /api/events/:uid/edit
- **auth:** oidcAuthMiddleware
- **params:** uid (path)
- **body:** CreateEventPayload
- **file:** apps/api/src/routes/events.ts
- **response:** 202 { uid: string }
- **description:** Enqueues update (or delete+create pair for calendar-move) to calendarOutbox. Async write-back.

## `DELETE /api/events/:uid`

- **method:** DELETE
- **path:** /api/events/:uid
- **auth:** oidcAuthMiddleware
- **params:** uid (path)
- **file:** apps/api/src/routes/events.ts
- **response:** 202 { uid: string }
- **description:** Enqueues delete to calendarOutbox with cached etag (If-Match). Async write-back.

## `GET /api/events/sync-status`

- **method:** GET
- **path:** /api/events/sync-status
- **auth:** oidcAuthMiddleware
- **params:** uid (query, required)
- **file:** apps/api/src/routes/events.ts
- **response:** { uid: string, status: 'pending'|'done'|'failed'|'dead', error?: string }
- **description:** Outbox status poll for a given event UID, scoped to current member. Used by SyncStateToast.

## `GET /api/events/writable-calendars`

- **method:** GET
- **path:** /api/events/writable-calendars
- **auth:** oidcAuthMiddleware
- **file:** apps/api/src/routes/events.ts
- **response:** { calendars: [{ url, displayName, color, isShared }] }
- **description:** Authoritative D-03 writable set: member's own calendars + shared Family calendar. Client never derives this itself.

## `GET /api/sse/heartbeat`

- **method:** GET
- **path:** /api/sse/heartbeat
- **auth:** oidcAuthMiddleware
- **file:** apps/api/src/routes/sse.ts
- **response:** text/event-stream — event: heartbeat, data: { ts, id } every 10s
- **description:** SSE smoke-test endpoint for Pangolin tunnel validation. Phase 4 list-sync events not yet wired.