From c6ada08a945e71c5dd0a6a1bb9e5900ddc1e5981 Mon Sep 17 00:00:00 2001
From: shamoon <4887959+shamoon@users.noreply.github.com>
Date: Tue, 22 Sep 2026 20:12:48 -0700
Subject: [PATCH] Docs

---
 docs/widgets/info/customapi.md     | 35 ++++++++++++++++++++++++++++++
 docs/widgets/info/index.md         |  1 +
 docs/widgets/services/customapi.md |  2 ++
 mkdocs.yml                         |  1 +
 4 files changed, 39 insertions(+)
 create mode 100644 docs/widgets/info/customapi.md

diff --git a/docs/widgets/info/customapi.md b/docs/widgets/info/customapi.md
new file mode 100644
index 000000000..5489f48b5
--- /dev/null
+++ b/docs/widgets/info/customapi.md
@@ -0,0 +1,35 @@
+---
+title: Custom API
+description: Custom API Information Widget Configuration
+---
+
+_(Find the Custom API service widget [here](../services/customapi.md))_
+
+The Custom API information widget shows values from a custom self-hosted or third party API in your Homepage header, alongside an icon.
+
+```yaml
+- customapi:
+    url: http://custom.api.host.or.ip:port/path/to/exact/api/endpoint
+    icon: mdi-api # optional, see below
+    href: https://custom.api.host # optional, makes the widget a link
+    refreshInterval: 10000 # optional - in milliseconds, defaults to 10s
+    username: username # auth - optional
+    password: password # auth - optional
+    method: GET # optional, e.g. POST
+    headers: # optional, must be object
+      X-API-Token: token
+    requestBody: # optional, can be string or object
+    mappings:
+      - field: key
+        label: Field 1
+      - field: path.to.key2
+        label: Field 2
+        format: number # optional - defaults to text
+      - field: path.to.key3
+        label: Field 3
+        format: percent
+```
+
+The `icon` accepts the same values as [service icons](../../configs/services.md#icons), e.g. `mdi-api`, `si-github`, `sh-homepage`, a dashboard icon name like `homepage.png`, or a full URL. If no icon is set, a generic API icon is shown.
+
+Mappings support the same `field`, `format`, `remap`, `scale`, `prefix` and `suffix` options as the [Custom API service widget](../services/customapi.md). The `additionalField` option and the `display` modes are not supported.
diff --git a/docs/widgets/info/index.md b/docs/widgets/info/index.md
index 961d93a68..f6ddce26a 100644
--- a/docs/widgets/info/index.md
+++ b/docs/widgets/info/index.md
@@ -7,6 +7,7 @@ search:
 
 You can also find a list of all available info widgets in the sidebar navigation.
 
+- [Custom API](customapi.md)
 - [Date & Time](datetime.md)
 - [Glances](glances.md)
 - [Greeting](greeting.md)
diff --git a/docs/widgets/services/customapi.md b/docs/widgets/services/customapi.md
index c820a21bb..3d0b55b68 100644
--- a/docs/widgets/services/customapi.md
+++ b/docs/widgets/services/customapi.md
@@ -3,6 +3,8 @@ title: Custom API
 description: Custom Widget Configuration from the API
 ---
 
+_(Find the Custom API information widget [here](../info/customapi.md))_
+
 This widget can show information from custom self-hosted or third party API.
 
 Fields need to be defined in the `mappings` section YAML object to correlate with the value in the APIs JSON object. Final field definition needs to be the key with the desired value information.
diff --git a/mkdocs.yml b/mkdocs.yml
index f1a8936d9..0af27d41b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -194,6 +194,7 @@ nav:
           - widgets/services/zabbix.md
       - "Information Widgets":
           - widgets/info/index.md
+          - widgets/info/customapi.md
           - widgets/info/datetime.md
           - widgets/info/glances.md
           - widgets/info/greeting.md