API Surface

API Surface

This page lists the current workers/bookmarks-api-worker HTTP API.

System

Method	Route	Auth	Notes
GET	/health	None	Worker health probe.

Auth

Method	Route	Auth	Notes
POST	/v1/auth/dev-login	None	Dev-only identity bootstrap.
POST	/v1/auth/login	None	Proxies to cosmos-auth-worker.
POST	/v1/auth/register	None	Proxies to cosmos-auth-worker.
POST	/v1/auth/password/reset-request	None	Proxies to cosmos-auth-worker.
POST	/v1/auth/password/reset-confirm	None	Proxies to cosmos-auth-worker.
POST	/v1/auth/refresh	None	Proxies to cosmos-auth-worker.

Profile

Method	Route	Auth	Notes
GET	/v1/me	Authenticated	Returns current user context.
GET	/v1/profile	Authenticated	Returns persisted profile fields.
PATCH	/v1/profile	Authenticated	Updates display/profile contact fields.
PATCH	/v1/profile/theme	Authenticated	Updates stored theme preference.

Clubs, Members, Books, Meetings

Method	Route	Auth	Notes
GET	/v1/clubs	Authenticated	Club list with role summary.
POST	/v1/clubs	Authenticated	Creates club and first book; creator becomes admin.
GET	/v1/clubs/:clubId/settings	Club member	Reads club settings + member list.
PATCH	/v1/clubs/:clubId	Club admin	Updates club name/description.
POST	/v1/clubs/:clubId/join	Authenticated	Joins as member (INSERT OR IGNORE).
GET	/v1/clubs/:clubId/users/search	Club admin	Searches existing users not already in the club for invite selection.
POST	/v1/clubs/:clubId/members	Club admin	Adds/invites an existing user by userId and role.
PATCH	/v1/clubs/:clubId/members/:memberUserId	Club admin	Changes member role; enforces last-admin guard.
DELETE	/v1/clubs/:clubId/members/:memberUserId	Club admin	Removes member; enforces last-admin guard.
GET	/v1/clubs/:clubId/books	Authenticated	Returns book list for club context.
POST	/v1/clubs/:clubId/books	Club member	Creates book in club.
PATCH	/v1/books/:bookId	Club admin	Updates title/chapter/description/spine color.
PATCH	/v1/books/:bookId/state	Club admin	Updates is_finished/is_current state.
PATCH	/v1/books/:bookId/rating	Club member	Upserts member’s rating.
DELETE	/v1/books/:bookId	Club admin	Deletes book and dependent book data.
GET	/v1/clubs/:clubId/meetings	Club member	Returns meetings plus RSVP summaries.
POST	/v1/clubs/:clubId/meetings	Club member	Creates meeting linked to a club book (bookId).
PATCH	/v1/meetings/:meetingId	Meeting creator or club admin	Updates meeting details.
POST	/v1/meetings/:meetingId/rsvp	Club member	Upserts member RSVP.
POST	/v1/meetings/:meetingId/cancel	Meeting creator or club admin	Marks meeting canceled.
DELETE	/v1/meetings/:meetingId	Club admin	Deletes meeting and meeting-linked rows.
GET	/v1/meetings/:meetingId/calendar	Club member	Generates ICS payload.
GET	/v1/meetings/:meetingId/comments	Club member	Lists meeting comments.
POST	/v1/meetings/:meetingId/comments	Club member	Creates meeting comment.
PATCH	/v1/meeting-comments/:commentId	Comment author + club member	Edits meeting comment body.
DELETE	/v1/meeting-comments/:commentId	Club admin	Deletes meeting comment.

Notes, Sections, Comments, Reactions, Assets

Method	Route	Auth	Notes
GET	/v1/clubs/:clubId/notes	Club member	Returns sectioned notes; supports bookId, sectionType, spoiler query params.
POST	/v1/clubs/:clubId/note-sections	Club member	Creates chapter/character/event section for a book.
POST	/v1/clubs/:clubId/notes	Club member	Creates note in a section.
PATCH	/v1/notes/:noteId	Note author + club member	Edits note body/spoiler level.
DELETE	/v1/notes/:noteId	Club admin	Deletes note and dependents.
GET	/v1/notes/:noteId/comments	Club member	Lists note comments (including replies).
POST	/v1/notes/:noteId/comments	Club member	Creates note comment/reply.
PATCH	/v1/comments/:commentId	Comment author + club member	Edits note comment body/spoiler level.
DELETE	/v1/comments/:commentId	Club admin	Deletes comment subtree recursively.
POST	/v1/notes/:noteId/reactions	Authenticated	Adds reaction (INSERT OR IGNORE).
POST	/v1/notes/:noteId/assets	Authenticated	Stores note asset metadata record.
DELETE	/v1/assets/:assetId	Club admin	Deletes asset metadata record.

Realtime

Method	Route	Auth	Notes
GET	/v1/clubs/:clubId/stream	Club member + websocket upgrade	Proxies websocket to Durable Object room.

Error shape

Validation and authorization failures return JSON error payloads:

{ "error": "message" }

Typical status codes: 400, 401, 403, 404, 409, 426, 500.

For role/action mapping, see Authorization Matrix.