diff --git a/api.capnp b/api.capnp
index eab2649..7b04351 100644
--- a/api.capnp
+++ b/api.capnp
@@ -92,11 +92,16 @@ interface Machine {
     # Try to use a machine. Fails if the user doesn't have enough permissions
 
     interface Check {
-        ok @0 () -> ();
+        ok @0 () -> (); # The machine was clean & ok. -> free
         not_ok @1 () -> ();
+        # The machine was left in an unacceptable state.
+        # Most likely marks the machine as `blocked` and somehow informs the previous user.
     }
 
     check @2 () -> ( chk :Maybe(Check) );
+    # After a machine has been used by an user with low enough permissions it's
+    # in the 'toCheck' state.  This call then allows more priviledged users to
+    # "check" the machine and move it to the `free` state.
 
     reserve @3 () -> ( rsrv :Maybe(AnyPointer) );
 }
@@ -104,6 +109,9 @@ interface Machine {
 interface Machines {
     lookup @0 ( uuid :UUID ) -> ( machine :Maybe(Machine) );
     # Get a machine interface. Returns `none` if there is no Machine with the given uuid.
+
+    list @1 () -> ( machines :List(Machine) );
+    # List all machines
 }
 
 interface Permissions {