From 07b5c19907497e3421beecc7dc2236cef2d42a60 Mon Sep 17 00:00:00 2001
From: Mike Degatano <michael.degatano@gmail.com>
Date: Sun, 2 Mar 2025 17:37:06 -0500
Subject: [PATCH] Document system managed field for addons (#2226)

* Document system managed field for addons

* Adjusting wording from coderabbit feedback

* System managed fields separated into new endpoint

* Remove unnecessary changes
---
 docs/api/supervisor/endpoints.md | 38 +++++++++++++++++++++++++++-----
 docs/api/supervisor/models.md    |  1 +
 2 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/docs/api/supervisor/endpoints.md b/docs/api/supervisor/endpoints.md
index dbbe88a9..22c95c32 100644
--- a/docs/api/supervisor/endpoints.md
+++ b/docs/api/supervisor/endpoints.md
@@ -42,7 +42,8 @@ Return overview information about installed add-ons.
       "build": false,
       "url": null,
       "icon": false,
-      "logo": false
+      "logo": false,
+      "system_managed": false
     }
   ]
 }
@@ -165,7 +166,9 @@ Get details about an add-on
 | startup             | string             | The stage when the add-on is started (initialize, system, services, application, once) |
 | state               | string or null     | The state of the add-on (started, stopped)                                             |
 | stdin               | boolean            | `true` if the add-on accepts stdin commands                                            |
-| translations        | dictionary         | A dictionary containing content of translation files for the add-on |
+| system_managed      | boolean            | Indicates whether the add-on is managed by Home Assistant                              |
+| system_managed_config_entry | string     | Provides the configuration entry ID if the add-on is managed by Home Assistant         |
+| translations        | dictionary         | A dictionary containing content of translation files for the add-on                    |
 | udev                | boolean            | `true` if udev access is granted is enabled                                            |
 | update_available    | boolean            | `true` if an update is available                                                       |
 | url                 | string or null     | URL to more information about the add-on                                               |
@@ -241,6 +244,8 @@ Get details about an add-on
   "startup": "application",
   "state": "started",
   "stdin": false,
+  "system_managed": true,
+  "system_managed_config_entry": "abc123",
   "translations": {
     "en": {
       "configuration": {
@@ -275,9 +280,7 @@ Get the add-on logo
 </ApiEndpoint>
 
 <ApiEndpoint path="/addons/<addon>/options" method="post">
-Set the protection mode on an add-on.
-
-This function is not callable by itself and you can not use `self` as the slug here.
+Set the options for an add-on.
 
 :::tip
 To reset customized network/audio/options, set it `null`.
@@ -316,6 +319,31 @@ To reset customized network/audio/options, set it `null`.
 
 </ApiEndpoint>
 
+<ApiEndpoint path="/addons/<addon>/sys_options" method="post">
+Change options specific to system managed addons.
+
+This endpoint is only callable by Home Assistant and not by any other client.
+
+**Payload**
+
+| key                         | type          | description                             |
+| --------------------------- | ------------- | --------------------------------------- |
+| system_managed              | boolean       | `true` if managed by Home Assistant     |
+| system_managed_config_entry | boolean       | ID of config entry managing addon       |
+
+**You need to supply at least one key in the payload.**
+
+**Example payload:**
+
+```json
+{
+  "system_managed": true,
+  "system_managed_config_entry": "abc123"
+}
+```
+
+</ApiEndpoint>
+
 <ApiEndpoint path="/addons/<addon>/options/validate" method="post">
 Run a configuration validation against the current stored add-on configuration or payload.
 
diff --git a/docs/api/supervisor/models.md b/docs/api/supervisor/models.md
index 4a4bb19b..cb00f0dd 100644
--- a/docs/api/supervisor/models.md
+++ b/docs/api/supervisor/models.md
@@ -21,6 +21,7 @@ These models are describing objects that are getting returned from the superviso
 | icon             | bool           | The add-on has an icon file                            |
 | logo             | bool           | The add-on has a logo file                            |
 | state            | string         | The state of the add-on (started, stopped)            |
+| system_managed   | bool           | Indicates whether the add-on is managed by Home Assistant |
 
 ## Application