From 32432026db1e92b6b4364afa6b240fb40fb6bc1e Mon Sep 17 00:00:00 2001
From: Nils Schneider <nils.schneider@posteo.de>
Date: Tue, 14 Oct 2025 22:37:20 +0200
Subject: [PATCH] backend: health without auth

---
 backend/src/routes/mod.rs |  2 +-
 docs/api.txt              | 56 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)
 create mode 100644 docs/api.txt

diff --git a/backend/src/routes/mod.rs b/backend/src/routes/mod.rs
index f0dcc46..5ed956c 100644
--- a/backend/src/routes/mod.rs
+++ b/backend/src/routes/mod.rs
@@ -100,12 +100,12 @@ pub fn create_router(state: AppState) -> Router<()> {
         .nest("/api/documents", documents_routes)
         .nest("/api/folders", folders_routes)
         .nest("/api/tags", tags_routes)
-        .route("/api/health", get(health::health_check))
         .layer(middleware::from_extractor_with_state::<AuthenticatedUser, _>(protected_state));
 
     Router::new()
         .merge(download_routes)
         .nest("/api/auth", auth_routes)
+        .route("/api/health", get(health::health_check))
         .merge(protected_routes)
         .with_state(state)
         .layer(cors)
diff --git a/docs/api.txt b/docs/api.txt
new file mode 100644
index 0000000..6282896
--- /dev/null
+++ b/docs/api.txt
@@ -0,0 +1,56 @@
+Papercrate REST API
+===================
+
+Unless noted otherwise, endpoints below require a valid `Authorization: Bearer <token>` header.
+
+Authentication
+--------------
+- POST /api/auth/login - Exchange username/password for an access token and refresh cookie (public).
+- POST /api/auth/refresh - Rotate the refresh cookie and return a new access token (public, requires refresh cookie).
+- POST /api/auth/logout - Revoke the caller's refresh tokens and clear the cookie.
+- GET  /api/auth/me - Return the authenticated principal payload.
+
+Health
+------
+- GET  /api/health - Lightweight liveness probe (no authentication required).
+
+Documents
+---------
+- GET  /api/documents - List documents, optionally filtered by `folder_id` and `include_deleted`.
+- POST /api/documents - Upload a document via multipart form-data (`file`, optional metadata/folder fields).
+- POST /api/documents/reanalyze - Queue re-analysis for every non-deleted document.
+- POST /api/documents/bulk/move - Move multiple documents to a target folder.
+- POST /api/documents/bulk/tags - Add or remove tags across multiple documents.
+- POST /api/documents/bulk/reanalyze - Queue re-analysis jobs for selected documents.
+- GET  /api/documents/:id - Retrieve metadata and current version details for a document.
+- PATCH /api/documents/:id - Update document metadata (currently title).
+- DELETE /api/documents/:id - Soft-delete a document.
+- GET  /api/documents/:id/download - Create a pre-signed download URL for the current version.
+- PATCH /api/documents/:id/folder - Move a document to another folder.
+- POST /api/documents/:id/tags - Assign one or more tags to a document.
+- DELETE /api/documents/:id/tags/:tag_id - Remove a single tag from a document.
+
+Document Assets
+---------------
+- GET  /api/documents/:id/assets - List generated assets for the current version.
+- POST /api/documents/:id/assets - Request (re)generation of document assets; accepts optional `force` query flag.
+- GET  /api/documents/:id/assets/:asset_id - Fetch metadata and a pre-signed URL for a specific asset.
+
+Downloads
+---------
+- GET  /download/:token - Follow a one-time download token; redirects to a pre-signed URL (public token required).
+
+Folders
+-------
+- POST /api/folders - Create a folder (optionally under a parent).
+- POST /api/folders/path - Ensure a nested folder path exists, creating missing segments.
+- GET  /api/folders/:id/contents - List subfolders and documents inside a folder; use `root` for the workspace root.
+- GET  /api/folders/:id/documents - Search within a folder tree with optional `query` and `tags` filters.
+- DELETE /api/folders/:id - Soft-delete a folder.
+- PATCH /api/folders/:id - Change a folder's parent.
+
+Tags
+----
+- GET  /api/tags - List all tags with usage counts.
+- POST /api/tags - Create a new tag.
+- PATCH /api/tags/:id - Update a tag's label or color.