docs(api): deprecate StartActionByGet and StartActionByGetAndWait

As decided in #1028, the ByGet methods are deprecated and will be removed.

- Drop them from the method table; recommend StartAction and
  StartActionAndWait instead.
- Turn their method pages into deprecation notices with migration
  examples, and add a migration table to start_action.adoc.
- Home Assistant now uses StartAction with bindingId.
- Label them "(deprecated)" in the nav.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/modules/ROOT/nav.adoc

@@ -182,8 +182,8 @@
 * xref:api/intro.adoc[API]
 ** xref:api/start_action.adoc[Start Actions from the API]
 *** xref:api/method_StartAction.adoc[StartAction]
-*** xref:api/method_StartActionByGet.adoc[StartActionByGet]
 *** xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
-*** xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]
+*** xref:api/method_StartActionByGet.adoc[StartActionByGet (deprecated)]
+*** xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait (deprecated)]
 ** xref:api/misc.adoc[Misc API calls]
 ** xref:api/login.adoc[Local user login via the API]

docs/modules/ROOT/pages/api/method_StartActionByGet.adoc

@@ -1,37 +1,23 @@
-= API Method: StartActionByGet
+= API Method: StartActionByGet (deprecated)
 
-This is the simplest method to start an action - you only need to send the action ID, which makes it a good fit for quick integrations (Stream Deck, Home Assistant, cron jobs, etc). You cannot pass arguments using this method.
-
-* **HTTP Method**: `POST`
-* **Request Type**: xref:api/start_action.adoc#api-request-actionid[Action ID only] (`actionId`)
-* **Response Type**: Execution Tracking ID
-
-NOTE: For actions generated from xref:entities/intro.adoc[entities], `actionId` must be the entity's binding ID, not the action `id` from your `config.yaml` - see xref:api/start_action.adoc#api-ids[Action IDs vs Binding IDs]. For normal actions, the two are the same.
-
-[NOTE]
+[WARNING]
 ====
-Despite the name, in OliveTin 3k this method is called with `POST` and a JSON body, the same as every other API method. The OliveTin 2k style of putting the action ID in the URL (eg: `GET /api/StartActionByGet/pingGithub`) is no longer supported and returns `404`.
+`StartActionByGet` is **deprecated** and will be removed in a future version of OliveTin. Use xref:api/method_StartAction.adoc[StartAction] instead.
+
+Despite its name, this method no longer supports `GET` requests. The OliveTin 2k style of putting the action ID in the URL (eg: `GET /api/StartActionByGet/pingGithub`) returns `404` in OliveTin 3k, and is not coming back.
 ====
 
-include::partial$api/start_action_methods.adoc[]
+== Migrating to `StartAction`
 
-[#api-eg-startActionId]
-== Example API call: Start an action by ID
+`StartActionByGet` takes only an `actionId`, and returns an Execution Tracking ID. `StartAction` does the same with `bindingId` - for a normal action, the binding ID is the same as the action `id` from your `config.yaml` (see xref:api/start_action.adoc#api-ids[Action IDs vs Binding IDs]).
 
-.curl
+.Before (deprecated)
 ----
 user@host: curl http://olivetin.example.com:1337/api/StartActionByGet --json '{"actionId": "pingGithub"}'
-{"executionTrackingId":"ff7d6f13-af8f-4ebe-8174-ad4cc7197b45"}
 ----
 
-The corresponding config.yaml would look like this;
-
-[source,yaml]
+.After
 ----
-actions:
-  - title: Ping GitHub.com
-    id: pingGithub
-    shell: ping github.com -c 1
+user@host: curl http://olivetin.example.com:1337/api/StartAction --json '{"bindingId": "pingGithub"}'
+{"executionTrackingId":"ff7d6f13-af8f-4ebe-8174-ad4cc7197b45"}
 ----
-
-IDs are used by these API calls, as you probably want the interface to display a human-readable title, whereas the API call doesn't want to have spaces or punctuation.

docs/modules/ROOT/pages/api/method_StartActionByGetAndWait.adoc

@@ -1,28 +1,23 @@
-= API Method: StartActionByGetAndWait
+= API Method: StartActionByGetAndWait (deprecated)
 
-This method is also a very easy way to quickly start an action, but it waits for the action to finish before returning the result. This is useful if you want to get the output of the action or check its result without having to poll for it. You cannot pass arguments using this method.
-
-* **HTTP Method**: `POST`
-* **Request Type**: xref:api/start_action.adoc#api-request-actionid[Action ID only] (`actionId`)
-* **Response Type**: Log Entry (waits for the action to finish)
-
-NOTE: For actions generated from xref:entities/intro.adoc[entities], `actionId` must be the entity's binding ID, not the action `id` from your `config.yaml` - see xref:api/start_action.adoc#api-ids[Action IDs vs Binding IDs]. For normal actions, the two are the same.
-
-[NOTE]
-====
-Despite the name, in OliveTin 3k this method is called with `POST` and a JSON body. The OliveTin 2k style of putting the action ID in the URL (eg: `GET /api/StartActionByGetAndWait/pingGithub`) is no longer supported and returns `404`.
+[WARNING]
 ====
+`StartActionByGetAndWait` is **deprecated** and will be removed in a future version of OliveTin. Use xref:api/method_StartActionAndWait.adoc[StartActionAndWait] instead.
 
-There are several variants of this API call available which might be easier for scripts (or humans) to work with:
+Despite its name, this method no longer supports `GET` requests. The OliveTin 2k style of putting the action ID in the URL (eg: `GET /api/StartActionByGetAndWait/pingGithub`) returns `404` in OliveTin 3k, and is not coming back.
+====
 
-include::partial$api/start_action_methods.adoc[]
+== Migrating to `StartActionAndWait`
 
-== Example API call: Start an action by ID, and wait for it to finish
+`StartActionAndWait` takes the same `actionId` field, and returns the same Log Entry, so you only need to change the method name. It also accepts `arguments` and a `justification`.
 
-.curl
+.Before (deprecated)
 ----
 user@host: curl http://olivetin.example.com:1337/api/StartActionByGetAndWait --json '{"actionId": "pingGithub"}'
-{"logEntry":{"actionTitle":"Ping GitHub.com","output":"...","exitCode":0, ... }}
 ----
 
-See xref:api/start_action.adoc#api-response-logentry[Response type: LogEntry] for the full response.
+.After
+----
+user@host: curl http://olivetin.example.com:1337/api/StartActionAndWait --json '{"actionId": "pingGithub"}'
+{"logEntry":{"actionTitle":"Ping GitHub.com","output":"...","exitCode":0, ... }}
+----

docs/modules/ROOT/pages/api/start_action.adoc

@@ -1,7 +1,7 @@
 [#api-start-action]
 = Starting Actions from the API
 
-There are several variants of this API call available which might be easier for scripts (or humans) to work with!
+There are two API methods for starting actions: `StartAction`, which returns straight away, and `StartActionAndWait`, which waits for the action to finish.
 
 include::partial$api/start_action_methods.adoc[]
 
@@ -13,27 +13,7 @@ All request and response field names below are the protobuf JSON names (lowerCam
 * `actionId` is the `id` you set on the action in your `config.yaml`. To find your Action ID, and understand how Action IDs work, see the xref:action_customization/ids.adoc[Action ID] documentation.
 * `bindingId` identifies one button/instance of an action. For a normal action this is the same as the action ID. For actions generated from xref:entities/intro.adoc[entities], each entity gets its own binding ID. Binding IDs are returned by `GetDashboard` (as `action.bindingId`).
 
-NOTE: Despite its name, the `actionId` field used by `StartActionAndWait`, `StartActionByGet` and `StartActionByGetAndWait` is looked up as a binding ID. For normal actions this makes no difference, but for entity-generated actions you must send the entity's binding ID - sending the configured action `id` returns `not_found`.
-
-[#api-request-actionid]
-== Request type: Action ID only
-
-Used by:
-
-*** xref:api/method_StartActionByGet.adoc[StartActionByGet]
-*** xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]
-
-If you are trying to integrate OliveTin with your own scripts or processes, this is probably the easiest way to start actions. You cannot pass arguments with this request type.
-
-[source,json]
-.`StartActionByGetRequest` / `StartActionByGetAndWaitRequest`
-----
-{
-  "actionId": "string"
-}
-----
-
-See xref:api/method_StartActionByGet.adoc#api-eg-startActionId[the example].
+NOTE: Despite its name, the `actionId` field used by `StartActionAndWait` is looked up as a binding ID. For normal actions this makes no difference, but for entity-generated actions you must send the entity's binding ID - sending the configured action `id` returns `not_found`.
 
 [#api-request-startaction]
 == Request type: StartAction request object
@@ -105,7 +85,6 @@ Note that this request selects the action with `actionId` (not `bindingId`), and
 Used by:
 
 *** xref:api/method_StartAction.adoc[StartAction]
-*** xref:api/method_StartActionByGet.adoc[StartActionByGet]
 
 .Example Execution Tracking ID response
 [source,json]
@@ -119,7 +98,6 @@ Used by:
 Used by:
 
 *** xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
-*** xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]
 
 The `output` field contains the combined stdout and stderr of the action.
 
@@ -158,3 +136,21 @@ The `output` field contains the combined stdout and stderr of the action.
   }
 }
 ----
+
+[#api-deprecated-byget]
+== Deprecated: StartActionByGet and StartActionByGetAndWait
+
+`StartActionByGet` and `StartActionByGetAndWait` are deprecated, and will be removed in a future version of OliveTin. They only accept an `actionId` (no arguments), and despite their names they no longer support `GET` requests - the OliveTin 2k style of putting the action ID in the URL returns `404`.
+
+[%header]
+|===
+| Deprecated method | Use instead | Change
+
+| xref:api/method_StartActionByGet.adoc[StartActionByGet]
+| xref:api/method_StartAction.adoc[StartAction]
+| Send `{"bindingId": "..."}` instead of `{"actionId": "..."}`
+
+| xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]
+| xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
+| Change the method name only - the request is the same
+|===

docs/modules/ROOT/pages/integrations/homeassistant.adoc

@@ -19,13 +19,13 @@ actions:
     shell: ssh user@server "sudo systemctl suspend"
 ----
 
-You then need to know the URL to call to trigger this action. This is the OliveTin API URL plus the method name, and the action ID is sent in a JSON body. For example, if your OliveTin is running at `http://yourserver:1337`, you would `POST` `{"actionId": "server_sleep"}` to `http://yourserver:1337/api/StartActionByGet`.
+You then need to know the URL to call to trigger this action. This is the OliveTin API URL plus the method name, and the action is selected in a JSON body. For example, if your OliveTin is running at `http://yourserver:1337`, you would `POST` `{"bindingId": "server_sleep"}` to `http://yourserver:1337/api/StartAction`. (For a normal action, the `bindingId` is the same as the action `id`.)
 
-You can learn more about starting actions via the OliveTin API by reading the link xref:api/start_action.adoc[Starting Actions via the API] page, but the method "StartActionByGet" is the one you will want to use for Home Assistant. It returns as soon as the action has started.
+You can learn more about starting actions via the OliveTin API by reading the link xref:api/start_action.adoc[Starting Actions via the API] page, but the method "StartAction" is the one you will want to use for Home Assistant. It returns as soon as the action has started.
 
 [NOTE]
 ====
-Avoid `StartActionByGetAndWait` for Home Assistant unless you need the action's output:
+Avoid `StartActionAndWait` for Home Assistant unless you need the action's output:
 
 * It only responds once the action has finished, and Home Assistant's `rest_command` gives up after 10 seconds by default, so longer actions are reported as failed even though they ran.
 * It checks that the caller can view the action's logs *after* the action has run. Without the `logs` permission, Home Assistant gets an error even though the action ran, and retrying runs it again.
@@ -53,10 +53,10 @@ From the file editor now in your sidebar, browse the filesystem to the configura
 ----
 rest_command:
   olivetin_sleep_mindstorm:
-    url: http://olivetin.example.com:1337/api/StartActionByGet
+    url: http://olivetin.example.com:1337/api/StartAction
     method: post
     content_type: "application/json"
-    payload: '{"actionId": "server_sleep"}'
+    payload: '{"bindingId": "server_sleep"}'
 ----
 
 You save the file, and restart Home Assistant to pick up the changes.

docs/modules/ROOT/partials/api/start_action_methods.adoc

@@ -1,4 +1,4 @@
-There are 4 main methods to start an action in OliveTin, which can be used in scripts or other applications. These methods allow you to trigger actions either immediately or wait for them to complete. Like every OliveTin API method, they are called with an HTTP `POST` and a JSON request body (eg: `curl --json '{...}'`).
+There are 2 methods to start an action in OliveTin, which can be used in scripts or other applications. These methods allow you to trigger actions either immediately or wait for them to complete. Like every OliveTin API method, they are called with an HTTP `POST` and a JSON request body (eg: `curl --json '{...}'`).
 
 .Webhook/API reference table
 [%header]
@@ -10,23 +10,15 @@ There are 4 main methods to start an action in OliveTin, which can be used in sc
 | xref:api/start_action.adoc#api-request-startaction[`bindingId`, arguments, tracking ID, justification]
 | xref:api/start_action.adoc#api-response-trackingid[Execution Tracking ID]
 
-| xref:api/method_StartActionByGet.adoc[StartActionByGet]
-| POST
-| xref:api/start_action.adoc#api-request-actionid[`actionId` only]
-| xref:api/start_action.adoc#api-response-trackingid[Execution Tracking ID]
-
 | xref:api/method_StartActionAndWait.adoc[StartActionAndWait]
 | POST
 | xref:api/start_action.adoc#api-request-startactionandwait[`actionId`, arguments, justification]
 | xref:api/start_action.adoc#api-response-logentry[Log Entry (waits for the action to finish)]
 
-| xref:api/method_StartActionByGetAndWait.adoc[StartActionByGetAndWait]
-| POST
-| xref:api/start_action.adoc#api-request-actionid[`actionId` only]
-| xref:api/start_action.adoc#api-response-logentry[Log Entry (waits for the action to finish)]
-
 |======================================================
 
-NOTE: The waiting methods (`StartActionAndWait` and `StartActionByGetAndWait`) check that the caller is allowed to view the action's logs *after* the action has finished. A caller that can start an action but cannot view its logs receives a permission error, even though the action has already run - so retrying on that error can run the action again. Use `StartAction` or `StartActionByGet` when you do not need the log entry.
+NOTE: `StartActionAndWait` checks that the caller is allowed to view the action's logs *after* the action has finished. A caller that can start an action but cannot view its logs receives a permission error, even though the action has already run - so retrying on that error can run the action again. Use `StartAction` when you do not need the log entry.
+
+WARNING: `StartActionByGet` and `StartActionByGetAndWait` are xref:api/start_action.adoc#api-deprecated-byget[deprecated] and will be removed in a future version. Use `StartAction` or `StartActionAndWait` instead.
 
 You can also browse these methods in the link:https://docs.olivetin.app/api/swagger/3k/[OpenAPI/Swagger] docs if you prefer. The link:https://github.com/OliveTin/OliveTin/blob/main/proto/olivetin/api/v1/olivetin.proto[Protobuf definition] is the source of truth for all request and response fields.