diff --git a/docs/api/api.rst b/docs/api/api.rst
--- a/docs/api/api.rst
+++ b/docs/api/api.rst
@@ -16,9 +16,24 @@ API ACCESS FOR WEB VIEWS
 API access can also be turned on for each web view in RhodeCode that is
 decorated with `@LoginRequired` decorator. To enable API access simple change
 the standard login decorator to `@LoginRequired(api_access=True)`.
+
+To make this operation easier, starting from version 1.7.0 there's a white list
+of views that will have API access enabled. Simply edit `api_access_controllers_whitelist`
+option in your .ini file, and define views that should have API access enabled.
+Following example shows how to enable API access to patch/diff raw file and archive
+in RhodeCode::
+
+    api_access_controllers_whitelist =
+        ChangesetController:changeset_patch,
+        ChangesetController:changeset_raw,
+        FilesController:raw,
+        FilesController:archivefile
+
+
 After this change, a rhodecode view can be accessed without login by adding a
 GET parameter `?api_key=<api_key>` to url. By default this is only
-enabled on RSS/ATOM feed views.
+enabled on RSS/ATOM feed views. Exposing raw diffs is a good way to integrate with
+3rd party services like code review, or build farms that could download archives.
 
 
 API ACCESS
@@ -171,7 +186,7 @@ INPUT::
 OUTPUT::
 
     id : <id_given_in_input>
-    result : "Cache for repository `<reponame>` was invalidated: invalidated cache keys: <list_of_cache_keys>"
+    result : "Caches of repository `<reponame>`"
     error :  null
 
 lock
@@ -197,7 +212,13 @@ INPUT::
 OUTPUT::
 
     id : <id_given_in_input>
-    result : "User `<username>` set lock state for repo `<reponame>` to `true|false`"
+    result : {
+                 "repo": "<reponame>",
+                 "locked": "<bool true|false>",
+                 "locked_since": "<float lock_time>",
+                 "locked_by": "<username>",
+                 "msg": "User `<username>` set lock state for repo `<reponame>` to `<false|true>`"
+             }
     error :  null
 
 
@@ -302,6 +323,7 @@ OUTPUT::
     result: [
               {
                 "user_id" :     "<user_id>",
+                "api_key" :     "<api_key>",
                 "username" :    "<username>",
                 "firstname":    "<firstname>",
                 "lastname" :    "<lastname>",
@@ -333,7 +355,7 @@ INPUT::
     args :    {
                 "username" :  "<username>",
                 "email" :     "<useremail>",
-                "password" :  "<password>",
+                "password" :  "<password = Optional(None)>",
                 "firstname" : "<firstname> = Optional(None)",
                 "lastname" :  "<lastname> = Optional(None)",
                 "active" :    "<bool> = Optional(True)",
@@ -393,6 +415,7 @@ OUTPUT::
               "msg" : "updated user ID:<userid> <username>",
               "user": {
                 "user_id" :  "<user_id>",
+                "api_key" :  "<api_key>",
                 "username" : "<username>",
                 "firstname": "<firstname>",
                 "lastname" : "<lastname>",
@@ -461,6 +484,7 @@ OUTPUT::
                "members" :  [
                               {
                                 "user_id" :  "<user_id>",
+                                "api_key" :  "<api_key>",
                                 "username" : "<username>",
                                 "firstname": "<firstname>",
                                 "lastname" : "<lastname>",
@@ -518,8 +542,9 @@ INPUT::
     api_key : "<api_key>"
     method :  "create_users_group"
     args:     {
-                "group_name":  "<groupname>",
-                "active":"<bool> = Optional(True)"
+                "group_name": "<groupname>",
+                "owner" :     "<onwer_name_or_id = Optional(=apiuser)>",
+                "active":     "<bool> = Optional(True)"
               }
 
 OUTPUT::
@@ -642,6 +667,7 @@ OUTPUT::
                                   {
                                     "type":        "user",
                                     "user_id" :    "<user_id>",
+                                    "api_key" :    "<api_key>",
                                     "username" :   "<username>",
                                     "firstname":   "<firstname>",
                                     "lastname" :   "<lastname>",
@@ -667,6 +693,7 @@ OUTPUT::
                                   {
                                     "user_id" :     "<user_id>",
                                     "username" :    "<username>",
+                                    "api_key" :     "<api_key>",
                                     "firstname":    "<firstname>",
                                     "lastname" :    "<lastname>",
                                     "email" :       "<email>",