DocumentSage

POST /api/upload

Upload an HTML or Markdown file. Same path = overwrite. isPublic defaults to false.

Header/Body	Value
X-API-Key	Your static API key (or use session cookie from login)
file	.html or .md file (multipart)
path	e.g. "reports/summary"
isPublic	"true" or "false" (default false)
interactive	"true" or "false" (default false) — inject editing toolbar

# Upload with curl curl -X POST http://localhost:3000/api/upload \ -H "X-API-Key: your-key" \ -F "file=@report.html" \ -F "path=reports/q1" \ -F "isPublic=true" # Response { "url": "http://localhost:3000/view/reports/q1", ... }

DELETE /api/pages/:path

Delete a page + its file. Requires valid session cookie or X-API-Key.

curl -X DELETE http://localhost:3000/api/pages/reports/q1 \ -H "X-API-Key: your-key"

GET /api/pages

List all pages (public only, or all with session cookie). Sorted newest first.

curl http://localhost:3000/api/pages

GET /view/:path

Shareable page URL. HTML is served as-is (full page); Markdown opens the client-side viewer. Any page is viewable by anyone with the link (read-only); private pages are just hidden from the grid. 404 if not found.

curl -L http://localhost:3000/view/reports/q1

GET /api/raw/:path

Raw file bytes used by the Markdown renderer. 404 if not found.

curl http://localhost:3000/api/raw/reports/q1

POST /api/save/:path

Persist edits to an interactive page. Called by the injected editing toolbar (Ctrl+S). Body is the full document — raw text/html or text/markdown. Private pages: anyone with the link can save, no auth. Public pages: session cookie, X-API-Key, or X-Admin-Password.

Save logic, server-side:

Step	Behaviour
1 · Lookup	Path must exist, else `404`. Page must have `interactive=true`, else `400`.
2 · Auth	Private page → open to everyone (guests included). Public page → session cookie, `X-API-Key`, or `X-Admin-Password`, else `401`.
3 · Strip injection	For HTML, the injected `<script data-ds-interactive>` tags are removed before writing, so they are never duplicated on next serve.
4 · Persist	Full document bytes are written to disk; metadata timestamp updates. `isPublic` / `interactive` flags are preserved.
5 · Response	`{ "ok": true, "path": "...", "updatedAt": "..." }`. No redirect — the page stays live.

Comments are stored inline as HTML comments and survive saves:

<h2>Q1 Results</h2>

# Save HTML (full document body) curl -X POST http://localhost:3000/api/save/reports/q1 \ -H "Content-Type: text/html" \ -H "X-Admin-Password: admin" \ --data-binary @edited.html # Save Markdown (raw text, comments preserved) curl -X POST http://localhost:3000/api/save/reports/q1 \ -H "Content-Type: text/markdown" \ -H "X-Admin-Password: admin" \ --data-binary @edited.md

GET /api/instructions

Plain-text guide for AI agents building editable HTML documents: which HTML patterns the interactive layer preserves, and which break it. Public, no auth.

curl http://localhost:3000/api/instructions

POST /api/auth/login

Login with admin password. Sets persistent JWT cookie.

curl -X POST http://localhost:3000/api/auth/login \ -H "Content-Type: application/json" \ -d '{"password":"admin"}'