docs: document file download routes

README.md

@@ -109,6 +109,24 @@ Response: {
 }
 ```
 
+#### Download File
+
+Use `/files/download` when the client should receive the stored file as an
+attachment instead of the JSON metadata returned by `/files/get`.
+
+```http
+GET /files/download?file_id=1
+# or
+GET /files/download?file_path=path/to/file.txt
+# or
+GET /files/download/path/to/file.txt
+```
+
+Text files are returned as `text/plain`. Binary files uploaded with
+`binary_content_b64` are decoded and returned as `application/octet-stream`.
+Both responses include a `Content-Disposition: attachment` header using the
+stored file name.
+
 #### List Files
 
 ```http

routes/index.ts

@@ -15,6 +15,8 @@ This is a simple file server API, it has the following API:
 /files/get?file_path=... - Get a file
 /files/list - List all files
 /files/upsert - Upsert a file
+/files/download?file_path=... - Download a file as an attachment
+/files/download/path/to/file.txt - Download a file by path as an attachment
 
 /events/list?since=... - List events since a given timestamp
 /events/list?event_type=... - List events filtered by event type

tests/routes/api-index.test.ts

@@ -0,0 +1,11 @@
+import { test, expect } from "bun:test"
+import { getTestServer } from "tests/fixtures/get-test-server"
+
+test("API index documents file download routes", async () => {
+  const { axios } = await getTestServer()
+  const res = await axios.get("/")
+  const html = res.data as string
+
+  expect(html).toContain("/files/download?file_path=...")
+  expect(html).toContain("/files/download/path/to/file.txt")
+})