x3
a407a1381a
- SETUP: local dev guide (env vars, DB migrate, backend/frontend, troubleshooting) - HOSTING: bare-metal guide (systemd + Nginx + TLS + backups) and Docker Compose guide (deploy, reverse proxy, updates, backup/restore) - API: REST contract with curl examples and Socket.IO event protocol - ARCHITECTURE: stack, data model, auth model, realtime design, theming - ROADMAP: webapp MVP/next steps plus Tauri desktop clients for Windows, macOS and Linux with release-binary plan
2.7 KiB
2.7 KiB
API Reference
Base URL: http://localhost:3000/api. Auth: Authorization: Bearer <jwt>.
Auth
POST /auth/register
{ "email": "a@example.com", "name": "Ada", "password": "secret123" }
-> 201 { user, token }. Errors: 400 validation, 409 email taken.
POST /auth/login
{ "email": "a@example.com", "password": "secret123" }
-> 200 { user, token }. Errors: 401 invalid credentials.
GET /auth/me
-> 200 { user }.
curl -X POST localhost:3000/api/auth/register \
-H 'Content-Type: application/json' \
-d '{"email":"a@example.com","name":"Ada","password":"secret123"}'
Workspaces
| Method | Path | Role | Description |
|---|---|---|---|
| GET | /workspaces |
member | List my workspaces |
| POST | /workspaces |
any logged-in | Create workspace (caller becomes owner) |
| GET | /workspaces/:id |
viewer+ | Get workspace |
| PATCH | /workspaces/:id |
admin+ | Rename |
| DELETE | /workspaces/:id |
owner | Delete |
| GET | /workspaces/:id/members |
viewer+ | List members |
| POST | /workspaces/:id/members |
admin+ | Invite {email, role} (role: admin/member/viewer) |
| PATCH | /workspaces/:id/members/:userId |
admin+ | Change role |
| DELETE | /workspaces/:id/members/:userId |
admin+ | Remove member |
Roles rank: viewer < member < admin < owner. Viewers read only.
Pages
| Method | Path | Description |
|---|---|---|
| GET | /pages/by-workspace/:workspaceId |
List pages (flat, client builds tree) |
| POST | /pages |
Create {workspace_id, parent_id?, title?} (member+) |
| GET | /pages/:id |
Get page + comments |
| PATCH | /pages/:id |
Update title/icon/cover/content/position/parent/archive (member+) |
| DELETE | /pages/:id |
Delete incl. children via FK cascade |
| GET | /pages/search/query?q=&workspace_id= |
Title search |
| POST | /pages/:id/comments |
Add comment {body} |
| DELETE | /pages/:pageId/comments/:commentId |
Delete (author or admin+) |
Content fields: content_json (TipTap JSON), content_html (rendered HTML).
Users
GET /users/search?email=— lookup for invites (auth required).
Health
GET /health->{ok:true, db:'up'}or503 {ok:false, db:'down'}.
Real-time (Socket.IO)
Connect: io(url, { auth: { token } }).
page:join { pageId }— join room; server checks workspace membership.page:edit { pageId, content_json, content_html }— persist + broadcast to others. Viewers are ignored server-side.typing { pageId, name }— broadcast typing indicator.- Server events:
page:updated { page, from? },page:deleted { id },comment:added { comment },presence:update { members: [{userId,email,name}] },error:message { error }.