API.md

API Reference

Authentication

Method	Endpoint	Auth	Description
GET	/api/auth/url	No	Get Google OAuth login URL
GET	/auth/callback	No	OAuth callback (exchanges code for tokens)
GET	/api/auth/me	Cookie	Get current user info
POST	/api/auth/logout	Cookie	Clear session cookie

Users (Admin only)

Method	Endpoint	Description
GET	/api/users	List all configured users
POST	/api/users	Add user { email, name, role }
PUT	/api/users/:email	Update user { name?, role? }
DELETE	/api/users/:email	Remove user

Boards

Method	Endpoint	Auth	Description
POST	/api/boards	User	Create board { name } → { id }
GET	/api/boards	User	List user's boards
GET	/api/boards/:id	User	Get board details
PATCH	/api/boards/:id	User	Update board { name?, folderId? }
DELETE	/api/boards/:id	Owner	Delete board

Board Members

Method	Endpoint	Description
DELETE	/api/boards/:id/members/:email	Remove member
PUT	/api/boards/:id/members/:email/role	Change role { role }

Share Links

Method	Endpoint	Description
POST	/api/boards/:id/share	Create share link { role, isPublic? }
GET	/api/boards/join/:token	Get share link info
POST	/api/boards/join/:token	Join board via share link

Folders

Method	Endpoint	Description
GET	/api/folders	List user's folders
POST	/api/folders	Create folder { name, color? }
PATCH	/api/folders/:id	Update folder { name?, color? }
DELETE	/api/folders/:id	Delete folder (boards moved to root)

Resources (Google Drive)

Method	Endpoint	Description
GET	/api/boards/:id/resources	List board resources
POST	/api/boards/:id/resources	Attach resource
DELETE	/api/boards/:id/resources/:rid	Remove resource
GET	/api/drive/files	List Google Drive files

Comments

Method	Endpoint	Description
GET	/api/boards/:id/comments	List comments
POST	/api/boards/:id/comments	Add comment { elementId, text }
DELETE	/api/boards/:id/comments/:cid	Delete comment

AI (Gemini)

Method	Endpoint	Description
POST	/api/ai/generate	Generate text content
POST	/api/ai/image	Generate image from prompt
POST	/api/ai/analyze	Analyze uploaded image

Audit Log

Method	Endpoint	Description
GET	/api/boards/:id/audit	Get audit log entries

---

WebSocket Protocol

Connect to ws://host/ — all messages are JSON.

Client → Server

Type	Fields	Description
join	boardId, user	Join board room
update	element	Create/update element (CRDT)
delete	id, version, deletedBy	Delete element (tombstone)
clear	—	Clear all elements
cursor	x, y, user, selectedIds?	Broadcast cursor position
cursor_leave	email	Cursor left the canvas
chat	message	Send chat message
typing	user	Typing indicator
canvas_lock	locked	Lock/unlock canvas

Server → Client

Type	Fields	Description
init	boardId, elements, tombstones	Initial board state
update	element	Relayed element update
delete	id, version, deletedBy	Relayed deletion
clear	—	Board cleared
members	members[]	Updated member list
reject	element	Server-authoritative conflict rejection
cursor	x, y, user, selectedIds?	Remote cursor position
chat	message	Remote chat message
typing	user	Remote typing indicator
resource_added	resource	Resource attached
resource_removed	resource	Resource detached
canvas_lock	locked	Canvas lock state changed