API design: Get unlock PIN immediately after locking macOS host (#20123)

API changes for the "Get unlock PIN immediately after locking macOS
host" story (https://github.com/fleetdm/fleet/issues/19545)

---------

Co-authored-by: Victor Lyuboslavsky <victor.lyuboslavsky@gmail.com>

docs/REST API/rest-api.md

@@ -4053,6 +4053,7 @@ To lock a macOS host, the host must have MDM turned on. To lock a Windows or Lin
 | Name       | Type              | In   | Description                                                                   |
 | ---------- | ----------------- | ---- | ----------------------------------------------------------------------------- |
 | id | integer | path | **Required**. ID of the host to be locked. |
+| view_pin | boolean | query | For macOS hosts, whether to return the unlock PIN. |
 
 #### Example
 
@@ -4062,6 +4063,20 @@ To lock a macOS host, the host must have MDM turned on. To lock a Windows or Lin
 
 `Status: 204`
 
+#### Example
+
+`POST /api/v1/fleet/hosts/123/lock?view_pin=true`
+
+##### Default response (macOS hosts)
+
+`Status: 200`
+
+```json
+{
+  "unlock_pin": "123456"
+}
+```
+
 ### Unlock host
 
 _Available in Fleet Premium_
@@ -4097,7 +4112,6 @@ To unlock a Windows or Linux host, the host must have [scripts enabled](https://
 }
 ```
 
-
 ### Wipe host
 
 Sends a command to wipe the specified macOS, Windows, or Linux host. The host is wiped once it comes online.