From f1b1daf7519a8cb80365f832fe38f3fa11564798 Mon Sep 17 00:00:00 2001
From: colin <colin@nixc.us>
Date: Fri, 4 Jul 2025 22:37:57 -0400
Subject: [PATCH] Update API documentation to clarify approval workflow for
 API-created transactions

---
 docker/ploughshares/templates/api_docs.html | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docker/ploughshares/templates/api_docs.html b/docker/ploughshares/templates/api_docs.html
index 4637342..390bd76 100644
--- a/docker/ploughshares/templates/api_docs.html
+++ b/docker/ploughshares/templates/api_docs.html
@@ -93,6 +93,10 @@
                 <h4 class="mt-4">3. Create New Transaction</h4>
                 <div class="bg-light p-3 mb-3">
                     <p><strong>POST</strong> <code>/api/transaction</code></p>
+                    <p class="alert alert-info">
+                        <i class="bi bi-info-circle"></i> <strong>Note:</strong> All transactions created via API are set to "pending approval" status by default. 
+                        They must be explicitly approved using the approval endpoint before being considered valid.
+                    </p>
                     
                     <h5>Complete Example:</h5>
                     <pre class="bg-dark text-light p-2"><code id="createTransaction">curl -X POST "http://{{ server_name }}/api/transaction" \
@@ -109,7 +113,7 @@
                     
                     <h5>Response:</h5>
                     <pre class="bg-dark text-light p-2"><code>{
-  "message": "Transaction created successfully",
+  "message": "Transaction created successfully and is pending approval",
   "transaction_id": 2
 }</code></pre>
                 </div>
@@ -117,6 +121,10 @@
                 <h4 class="mt-4">4. Update Transaction</h4>
                 <div class="bg-light p-3 mb-3">
                     <p><strong>PUT</strong> <code>/api/transaction/{id}</code></p>
+                    <p class="alert alert-info">
+                        <i class="bi bi-info-circle"></i> <strong>Note:</strong> This endpoint only updates transaction details.
+                        It does not change the approval status of a transaction. To approve a transaction, use the dedicated approval endpoint.
+                    </p>
                     
                     <h5>Complete Example:</h5>
                     <pre class="bg-dark text-light p-2"><code id="updateTransaction">curl -X PUT "http://{{ server_name }}/api/transaction/2" \
@@ -184,6 +192,11 @@
                 <h4 class="mt-4">7. Approve Transaction</h4>
                 <div class="bg-light p-3 mb-3">
                     <p><strong>POST</strong> <code>/api/transaction/{id}/approve</code></p>
+                    <p class="alert alert-warning">
+                        <i class="bi bi-exclamation-triangle"></i> <strong>Important:</strong> This endpoint provides human-in-the-loop verification.
+                        All transactions (especially those created via API) require explicit approval before being considered valid.
+                        The approver name is recorded for audit purposes.
+                    </p>
                     
                     <h5>Complete Example:</h5>
                     <pre class="bg-dark text-light p-2"><code id="approveTransaction">curl -X POST "http://{{ server_name }}/api/transaction/2/approve" \