From 004deddbef74281ba026ea3048ee43e9b02db19b Mon Sep 17 00:00:00 2001
From: Severin Ibarluzea <seve700@gmail.com>
Date: Wed, 17 Sep 2025 08:27:17 -0700
Subject: [PATCH] docs: document binary file uploads

---
 README.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/README.md b/README.md
index 75bee15..9b73592 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,34 @@ The returned file will contain either `text_content` or `binary_content_b64`.
 Provide either `text_content` for text files or `binary_content_b64` for
 binary data. The response will include whichever field was supplied.
 
+#### Add Binary Files
+
+To upload binary assets (for example, images or compiled artifacts) encode the
+file contents as Base64 and provide them via the `binary_content_b64` field.
+
+```http
+POST /files/upsert
+Content-Type: application/json
+
+{
+  "file_path": "assets/logo.png",
+  "binary_content_b64": "iVBORw0KGgoAAAANSUhEUgAA..."
+}
+
+Response: {
+  "file": {
+    "file_id": "42",
+    "file_path": "assets/logo.png",
+    "binary_content_b64": "iVBORw0KGgoAAAANSUhEUgAA...",
+    "created_at": "2024-01-01T00:00:00.000Z"
+  }
+}
+```
+
+The server persists the binary payload exactly as provided. When retrieving the
+file with `/files/get`, the same `binary_content_b64` string will be returned
+and can be decoded back to the original bytes in your client code.
+
 #### Get File
 
 ```http