diff --git a/documentation/toaster-manual/toaster-manual-reference.xml b/documentation/toaster-manual/toaster-manual-reference.xml
index 2a1b92daeb..6c51ad1d24 100644
--- a/documentation/toaster-manual/toaster-manual-reference.xml
+++ b/documentation/toaster-manual/toaster-manual-reference.xml
@@ -719,6 +719,170 @@
+
+
+ Remote Toaster Monitoring
+
+
+ Toaster has an API that allows remote management applications to
+ directly query the state of the Toaster server and its builds
+ in a machine-to-machine manner.
+ This API uses the
+ REST
+ interface and the transfer of JSON files.
+ For example, you might
+ monitor a build inside a container through well supported
+ known HTTP ports in order to easily access a Toaster server
+ inside the container.
+ In this example, when you use this direct JSON API, you avoid
+ having web page parsing against the display the user sees.
+
+
+
+ Checking Health
+
+
+ Before you use remote Toaster monitoring, you should do
+ a health check.
+ To do this, ping the Toaster server using the following call
+ to see if it is still alive:
+
+ http://host:port/health
+
+ Be sure to provide values for host
+ and port.
+ If the server is alive, you will get the response HTML:
+
+ <!DOCTYPE html>
+ <html lang="en">
+ <head><title>Toaster Health</title></head>
+ <body>Ok</body>
+ </html>
+
+
+
+
+
+ Determining Status of Builds in Progress
+
+
+ Sometimes it is useful to determine the status of a build
+ in progress.
+ To get the status of pending builds, use the following call:
+
+ http://host:port/toastergui/api/building
+
+ Be sure to provide values for host
+ and port.
+ The output is a JSON file that itemizes all builds in
+ progress.
+ This file includes the time in seconds since each
+ respective build started as well as the progress of the
+ cloning, parsing, and task execution.
+ The following is sample output for a build in progress:
+
+ {"count": 1,
+ "building": [
+ {"machine": "beaglebone",
+ "seconds": "463.869",
+ "task": "927:2384",
+ "distro": "poky",
+ "clone": "1:1",
+ "id": 2,
+ "start": "2017-09-22T09:31:44.887Z",
+ "name": "20170922093200",
+ "parse": "818:818",
+ "project": "my_rocko",
+ "target":
+ "core-image-minimal"
+ }]
+ }
+
+
+
+
+
+ Checking Status of Builds Completed
+
+
+ Once a build is completed, you get the status when you use
+ the following call:
+
+ http://host:port/toastergui/api/builds
+
+ Be sure to provide values for host
+ and port.
+ The output is a JSON file that itemizes all complete builds,
+ and includes build summary information.
+ The following is sample output for a completed build:
+
+ {"count": 1,
+ "builds": [
+ {"distro": "poky",
+ "errors": 0,
+ "machine":
+ "beaglebone",
+ "project": "my_rocko",
+ "stop": "2017-09-22T09:26:36.017Z",
+ "target": "quilt-native",
+ "seconds": "78.193",
+ "outcome": "Succeeded",
+ "id": 1,
+ "start": "2017-09-22T09:25:17.824Z",
+ "warnings": 1,
+ "name": "20170922092618"
+ }]
+ }
+
+
+
+
+
+ Determining Status of a Specific Build
+
+
+ Sometimes it is useful to determine the status of a specific
+ build.
+ To get the status of a specific build, use the following
+ call:
+
+ http://host:port/toastergui/api/build/ID
+
+ Be sure to provide values for host,
+ port, and ID.
+ In order to provide the value for ID,
+ you must check the status of the completed build.
+ See the
+ "Checking Status of Builds Completed"
+ section for more information.
+
+
+
+ The output is a JSON file that itemizes the specific build
+ and includes build summary information.
+ The following is sample output for a specific build:
+
+ {"build":
+ {"distro": "poky",
+ "errors": 0,
+ "machine": "beaglebone",
+ "project": "my_rocko",
+ "stop": "2017-09-22T09:26:36.017Z",
+ "target": "quilt-native",
+ "seconds": "78.193",
+ "outcome": "Succeeded",
+ "id": 1,
+ "start": "2017-09-22T09:25:17.824Z",
+ "warnings": 1,
+ "name": "20170922092618",
+ "cooker_log": "/opt/user/poky/build-toaster-2/tmp/log/cooker/beaglebone/build_20170922_022607.991.log"
+ }
+ }
+
+
+
+
+
Useful Commands