From d3f358deb3965e1c296d3b9363c475e4345477bf Mon Sep 17 00:00:00 2001
From: Jack Gaino <github@jackgaino.com>
Date: Mon, 17 Mar 2025 11:01:28 -0400
Subject: [PATCH] Document API behaviour for service response data (#2137)

* Document API behaviour for service response data

Adds documentation for a new query/JSON parameter called `return_response`. It allows users to retrieve service response data instead of state changes when calling a service using the API.

* Update documentation to match new implementation

* Fix typo

* Explicitly mention 400 in response

* Apply suggestions from code review

Co-authored-by: J. Nick Koston <nick+github@koston.org>

---------

Co-authored-by: Erik Montnemery <erik@montnemery.com>
Co-authored-by: J. Nick Koston <nick+github@koston.org>
---
 docs/api/rest.md | 65 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 61 insertions(+), 4 deletions(-)

diff --git a/docs/api/rest.md b/docs/api/rest.md
index 409f492b..c42c5240 100644
--- a/docs/api/rest.md
+++ b/docs/api/rest.md
@@ -636,7 +636,7 @@ You can pass an optional JSON object to be used as `service_data`.
 }
 ```
 
-Returns a list of states that have changed while the service was being executed.
+Returns a list of states that have changed while the service was being executed, and optionally response data, if supported by the service.
 
 ```json
 [
@@ -655,6 +655,57 @@ Returns a list of states that have changed while the service was being executed.
 ]
 ```
 
+:::tip
+The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system.
+:::
+
+If the service you're calling supports returning response data, you can retrieve it by adding `?return_response` to the URL. Your response will then contain both the list of changed entities and the service response data.
+
+```json
+{
+    "changed_states": [
+        {
+            "attributes": {},
+            "entity_id": "sun.sun",
+            "last_changed": "2024-04-22T20:45:54.418320-04:00",
+            "state": "below_horizon"
+        },
+        {
+            "attributes": {},
+            "entity_id": "binary_sensor.dropbox",
+            "last_changed": "2024-04-22T20:45:54.418320-04:00",
+            "state": "on"
+        }
+    ],
+    "service_response": {
+        "weather.new_york_forecast": {
+            "forecast": [
+                {
+                    "condition": "clear-night",
+                    "datetime": "2024-04-22T20:45:55.173725-04:00",
+                    "precipitation_probability": 0,
+                    "temperature": null,
+                    "templow": 6.0
+                },
+                {
+                    "condition": "rainy",
+                    "datetime": "2024-04-23T20:45:55.173756-04:00",
+                    "precipitation_probability": 60,
+                    "temperature": 16.0,
+                    "templow": 4.0
+                }
+            ]
+        }
+    }
+}
+```
+
+:::note
+Some services return no data, others optionally return response data, and some always return response data.
+
+If you don't use `return_response` when calling a service that must return data, the API will return a 400. Similarly, you will receive a 400 if you use `return_response` when calling a service that doesn't return any data.
+:::
+
 Sample `curl` commands:
 
 Turn the light on:
@@ -692,9 +743,15 @@ curl \
   http://localhost:8123/api/services/mqtt/publish
 ```
 
-:::tip
-The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system.
-:::
+Retrieve daily weather forecast information:
+
+```shell
+curl \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer TOKEN" \
+  -d '{"entity_id": "weather.forecast_home", "type": "daily"}' \
+  http://localhost:8123/api/services/weather/get_forecasts?return_response
+```
 
 </ApiEndpoint>