From 09449a814aaaf240f4b8527c33ddfa7ee4c86f10 Mon Sep 17 00:00:00 2001
From: Gareth George <garethgeorge97@gmail.com>
Date: Thu, 23 Jan 2025 20:39:20 -0800
Subject: [PATCH] chore: doc updates

---
 docs/content/2.docs/3.api.md                  | 38 +++++++++++++++++++
 .../3.cookbooks/1.command-hook-examples.md    | 10 +----
 2 files changed, 40 insertions(+), 8 deletions(-)
 create mode 100644 docs/content/2.docs/3.api.md

diff --git a/docs/content/2.docs/3.api.md b/docs/content/2.docs/3.api.md
new file mode 100644
index 00000000..c703f438
--- /dev/null
+++ b/docs/content/2.docs/3.api.md
@@ -0,0 +1,38 @@
+# API
+
+Backrest provides a limited HTTP API for interacting with the backrest service. To use the API authentication must be disabled (or you can optionally provide a username and password with basic auth headers) e.g. `curl -u user:password http://localhost:9898/v1/<endpoint>`
+
+All of Backrest's API endpoints are defined as a gRPC service and are exposed over HTTP by a JSON RPC gateway for easy scripting. For the full service definition see [service.proto](https://github.com/garethgeorge/backrest/blob/main/proto/v1/service.proto).
+
+::alert{type="warning"}
+Only the APIs documented below are considered stable, other endpoints may be subject to change.
+::
+
+### Backup API
+
+The backup API can be used to trigger execution of a plan e.g. 
+
+```
+curl -X POST 'localhost:9898/v1.Backrest/Backup' --data '{"value": "YOUR_PLAN_ID"}' -H 'Content-Type: application/json'
+```
+
+The request will block until the operation has completed. A 200 response means the backup completed successfully, if the request times out the operation will continue in the background.
+### Operations API 
+
+The operations API can be used to fetch operation history e.g. 
+
+```
+curl -X POST 'localhost:9898/v1.Backrest/GetOperations' --data '{}' -H 'Content-Type: application/json'
+```
+
+More complex selectors can be applied e.g. 
+
+```
+curl -X POST 'localhost:9898/v1.Backrest/GetOperations' --data '{"selector": {"planId": "YOUR_PLAN_ID"}}' -H 'Content-Type: application/json'
+```
+
+For details on the structure of operations returned see the [operations.proto](https://github.com/garethgeorge/backrest/blob/main/proto/v1/operations.proto).
+
+::alert{type="warning"}
+The structure of the operation history is subject to change over time. Different fields may be added or removed in future versions.
+::
diff --git a/docs/content/3.cookbooks/1.command-hook-examples.md b/docs/content/3.cookbooks/1.command-hook-examples.md
index 7b192fd6..e6edbcfa 100644
--- a/docs/content/3.cookbooks/1.command-hook-examples.md
+++ b/docs/content/3.cookbooks/1.command-hook-examples.md
@@ -14,7 +14,6 @@ When run on `CONDITION_SNAPSHOT_START` command hooks have the ability to send co
 
 ## Examples
 
-
 #### Notify a healthcheck service
 
 Ping a healthcheck service (e.g. https://healthchecks.io/ in the example) to notify it of backup status (or failure) using a command hook.
@@ -146,7 +145,8 @@ fi
 
 **Error Behavior:** `ON_ERROR_CANCEL`
 
-### Windows PowerShell examples
+## Windows Notification Examples
+
 #### GUI message box on error condition
 The message box stays on screen until acknowledged by the user. Use the same script for both backup plan and repo settings to catch errors.
 
@@ -163,8 +163,6 @@ $icon = [System.Windows.Forms.MessageBoxIcon]::Error
 $title = "Backrest"
 $message = '{{ .Summary }}'
 [System.Windows.Forms.MessageBox]::Show($message, $title, $buttons, $icon, $defbutton, $options)
-
-# Include this comment and the line above it. See https://github.com/garethgeorge/backrest/issues/400
 ```
 #### GUI toast warning notification
 Toast or app notifications appear for a short time before disappearing without user acknowledgement.
@@ -185,8 +183,6 @@ Start-Sleep -Seconds(5)
 $balloon.Visible = $false
 $balloon.Icon.Dispose()
 $balloon.Dispose()
-
-# Include this comment and the line above it. See https://github.com/garethgeorge/backrest/issues/400
 ```
 #### GUI toast information notification
 
@@ -206,6 +202,4 @@ Start-Sleep -Seconds(5)
 $balloon.Visible = $false
 $balloon.Icon.Dispose()
 $balloon.Dispose()
-
-# Include this comment and the line above it. See https://github.com/garethgeorge/backrest/issues/400
 ```