From af90cba909080fbacd4e710a0408e709b437d4c1 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Sat, 25 Oct 2025 19:06:00 -0700
Subject: [PATCH 1/2] tweak

---
 esphome/components/api/__init__.py         |  4 ++++
 esphome/components/api/api_server.h        |  3 +++
 esphome/components/api/custom_api_device.h | 12 ++++++++++++
 3 files changed, 19 insertions(+)

diff --git a/esphome/components/api/__init__.py b/esphome/components/api/__init__.py
index cf95da1bf0..363f5b73e1 100644
--- a/esphome/components/api/__init__.py
+++ b/esphome/components/api/__init__.py
@@ -258,6 +258,10 @@ async def to_code(config):
     if config.get(CONF_ACTIONS) or config[CONF_CUSTOM_SERVICES]:
         cg.add_define("USE_API_SERVICES")
 
+    # Set USE_API_CUSTOM_SERVICES if external components need dynamic service registration
+    if config[CONF_CUSTOM_SERVICES]:
+        cg.add_define("USE_API_CUSTOM_SERVICES")
+
     if config[CONF_HOMEASSISTANT_SERVICES]:
         cg.add_define("USE_API_HOMEASSISTANT_SERVICES")
 
diff --git a/esphome/components/api/api_server.h b/esphome/components/api/api_server.h
index 523a77262d..d29181250e 100644
--- a/esphome/components/api/api_server.h
+++ b/esphome/components/api/api_server.h
@@ -128,8 +128,11 @@ class APIServer : public Component, public Controller {
   void initialize_user_services(std::initializer_list<UserServiceDescriptor *> services) {
     this->user_services_.assign(services);
   }
+#ifdef USE_API_CUSTOM_SERVICES
+  // Only compile push_back method when custom_services: true (external components)
   void register_user_service(UserServiceDescriptor *descriptor) { this->user_services_.push_back(descriptor); }
 #endif
+#endif
 #ifdef USE_HOMEASSISTANT_TIME
   void request_time();
 #endif
diff --git a/esphome/components/api/custom_api_device.h b/esphome/components/api/custom_api_device.h
index 711eba2444..d34ccfa0ce 100644
--- a/esphome/components/api/custom_api_device.h
+++ b/esphome/components/api/custom_api_device.h
@@ -53,8 +53,14 @@ class CustomAPIDevice {
   template<typename T, typename... Ts>
   void register_service(void (T::*callback)(Ts...), const std::string &name,
                         const std::array<std::string, sizeof...(Ts)> &arg_names) {
+#ifdef USE_API_CUSTOM_SERVICES
     auto *service = new CustomAPIDeviceService<T, Ts...>(name, arg_names, (T *) this, callback);  // NOLINT
     global_api_server->register_user_service(service);
+#else
+    static_assert(
+        sizeof(T) == 0,
+        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
+#endif
   }
 #else
   template<typename T, typename... Ts>
@@ -86,8 +92,14 @@ class CustomAPIDevice {
    */
 #ifdef USE_API_SERVICES
   template<typename T> void register_service(void (T::*callback)(), const std::string &name) {
+#ifdef USE_API_CUSTOM_SERVICES
     auto *service = new CustomAPIDeviceService<T>(name, {}, (T *) this, callback);  // NOLINT
     global_api_server->register_user_service(service);
+#else
+    static_assert(
+        sizeof(T) == 0,
+        "register_service() requires 'custom_services: true' in the 'api:' section of your YAML configuration");
+#endif
   }
 #else
   template<typename T> void register_service(void (T::*callback)(), const std::string &name) {

From 4d391fb27e850efb204152f80de29d72c3165e6d Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Sat, 25 Oct 2025 19:12:21 -0700
Subject: [PATCH 2/2] missing define for analyzer

---
 esphome/core/defines.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/esphome/core/defines.h b/esphome/core/defines.h
index 8095ffed4a..97e766455a 100644
--- a/esphome/core/defines.h
+++ b/esphome/core/defines.h
@@ -123,6 +123,7 @@
 #define USE_API_NOISE
 #define USE_API_PLAINTEXT
 #define USE_API_SERVICES
+#define USE_API_CUSTOM_SERVICES
 #define API_MAX_SEND_QUEUE 8
 #define USE_MD5
 #define USE_SHA256