diff --git a/public/swagger/v1/entities/id.yaml b/public/swagger/v1/entities/id.yaml
index 399500b..570a176 100644
--- a/public/swagger/v1/entities/id.yaml
+++ b/public/swagger/v1/entities/id.yaml
@@ -18,6 +18,7 @@ paths:
     parameters:
     - $ref: "#/components/parameters/token"
     - $ref: "#/components/parameters/id"
+    - $ref: "#/components/parameters/md"
     responses:
       200:
         $ref: "#/components/schemas/responseOneResolved"
@@ -54,6 +55,13 @@ components:
       $ref: "../swagger.yaml#/components/parameters/token"
     id:
       $ref: "../swagger.yaml#/components/parameters/id"
+    md:
+      name: md
+      description: "render the text section as markdown"
+      in: query
+      required: false
+      schema:
+        type: bool
 
   schemas:
     requestOne:
diff --git a/public/swagger/v1/files/index.yaml b/public/swagger/v1/files/index.yaml
index 47fa665..81b8192 100644
--- a/public/swagger/v1/files/index.yaml
+++ b/public/swagger/v1/files/index.yaml
@@ -5,6 +5,7 @@ paths:
     - files
     parameters:
     - $ref: "#/components/parameters/token"
+    - $ref: "#/components/parameters/direct"
     requestBody:
       $ref: "#/components/schemas/requestForm"
 
@@ -12,6 +13,13 @@ components:
   parameters:
     token:
       $ref: "../swagger.yaml#/components/parameters/token"
+    direct:
+      name: direct
+      description: "interpret content as a direct link to actual content"
+      in: query
+      required: false
+      schema:
+        type: bool
   schemas:
     requestForm:
       $ref: "../swagger.yaml#/components/schemas/requestForm"
diff --git a/public/swagger/v1/index.yaml b/public/swagger/v1/index.yaml
new file mode 100644
index 0000000..ae90d8f
--- /dev/null
+++ b/public/swagger/v1/index.yaml
@@ -0,0 +1,6 @@
+paths:
+  get:
+    tags: []
+    summary: "Access a static read-only file server"
+    responses:
+      200: {}
diff --git a/public/swagger/v1/swagger.yaml b/public/swagger/v1/swagger.yaml
index 52fb096..f061555 100644
--- a/public/swagger/v1/swagger.yaml
+++ b/public/swagger/v1/swagger.yaml
@@ -15,24 +15,26 @@ servers:
 - url: http://api1.dndex.lan:8080/
 
 paths:
-  /version:
+  /api/version:
     $ref: "./version.yaml#/paths"
-  /dump:
+  /api/dump:
     $ref: "./dump.yaml#/paths"
-  /files:
+  /api/files:
     $ref: "./files/index.yaml#/paths"
-  /files/{path}:
+  /api/files/{path}:
     $ref: "./files/one.yaml#/paths"
-  /users/register:
+  /api/users/register:
     $ref: "./users/register.yaml#/paths"
-  /users/login:
+  /api/users/login:
     $ref: "./users/login.yaml#/paths"
-  /entities:
+  /api/entities:
     $ref: "./entities/index.yaml#/paths"
-  /entities/{id}:
+  /api/entities/{id}:
     $ref: "./entities/id.yaml#/paths"
-  /entities/{id}/{path}:
+  /api/entities/{id}/{path}:
     $ref: "./entities/idsub.yaml#/paths"
+  /:
+    $ref: "./index.yaml#/paths"
 
 components:
   parameters:
diff --git a/public/swagger/v1/users/login.yaml b/public/swagger/v1/users/login.yaml
index 6846361..481b0cb 100644
--- a/public/swagger/v1/users/login.yaml
+++ b/public/swagger/v1/users/login.yaml
@@ -6,13 +6,10 @@ paths:
     - users
     requestBody:
       content:
+        application/json:
+          $ref: "#/components/schemas/requestLogin"
         application/x-www-form-urlencoded:
-          schema:
-            type: object
-            properties:
-              DnDex-User:
-                type: string
-                example: "namespace"
+          $ref: "#/components/schemas/requestLogin"
     responses:
       200:
         content:
@@ -26,3 +23,13 @@ paths:
                 salt:
                   type: string
                   example: def-456
+
+components:
+  schemas:
+    requestLogin:
+      schema:
+        type: object
+        properties:
+          DnDex-User:
+            type: string
+            example: "namespace"
diff --git a/public/swagger/v1/users/register.yaml b/public/swagger/v1/users/register.yaml
index d360b09..11436ff 100644
--- a/public/swagger/v1/users/register.yaml
+++ b/public/swagger/v1/users/register.yaml
@@ -5,16 +5,10 @@ paths:
     - users
     requestBody:
       content:
+        application/json:
+          $ref: "#/components/schemas/requestRegister"
         application/x-www-form-urlencoded:
-          schema:
-            type: object
-            properties:
-              DnDex-User:
-                type: string
-                example: "namespace"
-              DnDex-Auth:
-                type: string
-                example: "password"
+          $ref: "#/components/schemas/requestRegister"
     responses:
       200:
         $ref: "#/components/schemas/responseOK"
@@ -23,3 +17,13 @@ components:
   schemas:
     responseOK:
       $ref: "../swagger.yaml#/components/schemas/responseOK"
+    requestRegister:
+      schema:
+        type: object
+        properties:
+          DnDex-User:
+            type: string
+            example: "namespace"
+          DnDex-Auth:
+            type: string
+            example: "password"