Docs

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.

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)

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.

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