--- a/docs/api/api.rst	Sun Feb 19 20:21:14 2012 +0200
+++ b/docs/api/api.rst	Sun Feb 26 17:25:09 2012 +0200
@@ -26,16 +26,18 @@
 
 All clients are required to send JSON-RPC spec JSON data::
 
-    {
+    {   
+        "id:<id>,
         "api_key":"<api_key>",
         "method":"<method_name>",
         "args":{"<arg_key>":"<arg_val>"}
     }
 
 Example call for autopulling remotes repos using curl::
-    curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'
+    curl https://server.com/_admin/api -X POST -H 'content-type:text/plain' --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'
 
 Simply provide
+ - *id* A value of any type, which is used to match the response with the request that it is replying to.
  - *api_key* for access and permission validation.
  - *method* is name of method to call
  - *args* is an key:value list of arguments to pass to method
@@ -47,7 +49,8 @@
 
 RhodeCode API will return always a JSON-RPC response::
 
-    {
+    {   
+        "id":<id>,
         "result": "<result>",
         "error": null
     }
@@ -72,21 +75,55 @@
     api_key : "<api_key>"
     method :  "pull"
     args :    {
-                "repo" : "<repo_name>"
+                "repo_name" : "<reponame>"
               }
 
 OUTPUT::
 
-    result : "Pulled from <repo_name>"
+    result : "Pulled from <reponame>"
     error :  null
 
 
+get_user
+--------
+
+Get's an user by username or user_id, Returns empty result if user is not found.
+This command can be executed only using api_key belonging to user with admin 
+rights.
+
+
+INPUT::
+
+    api_key : "<api_key>"
+    method :  "get_user"
+    args :    { 
+                "userid" : "<username or user_id>"
+              }
+
+OUTPUT::
+
+    result: None if user does not exist or 
+            {
+                "id" :       "<id>",
+                "username" : "<username>",
+                "firstname": "<firstname>",
+                "lastname" : "<lastname>",
+                "email" :    "<email>",
+                "active" :   "<bool>",
+                "admin" :    "<bool>",
+                "ldap_dn" :  "<ldap_dn>"
+            }
+
+    error:  null
+
+
 get_users
 ---------
 
 Lists all existing users. This command can be executed only using api_key
 belonging to user with admin rights.
 
+
 INPUT::
 
     api_key : "<api_key>"
@@ -104,18 +141,20 @@
                 "email" :    "<email>",
                 "active" :   "<bool>",
                 "admin" :    "<bool>",
-                "ldap" :     "<ldap_dn>"
+                "ldap_dn" :  "<ldap_dn>"
               },
     	      …
             ]
     error:  null
 
+
 create_user
 -----------
 
-Creates new user or updates current one if such user exists. This command can 
+Creates new user. This command can 
 be executed only using api_key belonging to user with admin rights.
 
+
 INPUT::
 
     api_key : "<api_key>"
@@ -123,9 +162,9 @@
     args :    {
                 "username" :  "<username>",
                 "password" :  "<password>",
-                "firstname" : "<firstname>",
-                "lastname" :  "<lastname>",
-                "email" :     "<useremail>"
+                "email" :     "<useremail>",
+                "firstname" : "<firstname> = None",
+                "lastname" :  "<lastname> = None",
                 "active" :    "<bool> = True",
                 "admin" :     "<bool> = False",
                 "ldap_dn" :   "<ldap_dn> = None"
@@ -134,15 +173,88 @@
 OUTPUT::
 
     result: {
+              "id" : "<new_user_id>",
               "msg" : "created new user <username>"
             }
     error:  null
 
+
+update_user
+-----------
+
+updates current one if such user exists. This command can 
+be executed only using api_key belonging to user with admin rights.
+
+
+INPUT::
+
+    api_key : "<api_key>"
+    method :  "update_user"
+    args :    {
+                "userid" : "<user_id or username>",
+                "username" :  "<username>",
+                "password" :  "<password>",
+                "email" :     "<useremail>",
+                "firstname" : "<firstname>",
+                "lastname" :  "<lastname>",
+                "active" :    "<bool>",
+                "admin" :     "<bool>",
+                "ldap_dn" :   "<ldap_dn>"
+              }
+
+OUTPUT::
+
+    result: {
+              "id" : "<edited_user_id>",
+              "msg" : "updated user <username>"
+            }
+    error:  null
+
+
+get_users_group
+---------------
+
+Gets an existing users group. This command can be executed only using api_key
+belonging to user with admin rights.
+
+
+INPUT::
+
+    api_key : "<api_key>"
+    method :  "get_users_group"
+    args :    {
+                "group_name" : "<name>"
+              }
+
+OUTPUT::
+
+    result : None if group not exist
+             {
+               "id" :         "<id>",
+               "group_name" : "<groupname>",
+               "active":      "<bool>",
+               "members" :  [
+                              { "id" :       "<userid>",
+                                "username" : "<username>",
+                                "firstname": "<firstname>",
+                                "lastname" : "<lastname>",
+                                "email" :    "<email>",
+                                "active" :   "<bool>",
+                                "admin" :    "<bool>",
+                                "ldap" :     "<ldap_dn>"
+                              },
+                              …
+                            ]
+             }
+    error : null
+
+
 get_users_groups
 ----------------
 
-Lists all existing users groups. This command can be executed only using api_key
-belonging to user with admin rights.
+Lists all existing users groups. This command can be executed only using 
+api_key belonging to user with admin rights.
+
 
 INPUT::
 
@@ -154,9 +266,9 @@
 
     result : [
                {
-                 "id" :       "<id>",
-                 "name" :     "<name>",
-                 "active":    "<bool>",
+                 "id" :         "<id>",
+                 "group_name" : "<groupname>",
+                 "active":      "<bool>",
                  "members" :  [
 	    	                    {
 	    	                      "id" :       "<userid>",
@@ -174,41 +286,6 @@
               ]
     error : null
 
-get_users_group
----------------
-
-Gets an existing users group. This command can be executed only using api_key
-belonging to user with admin rights.
-
-INPUT::
-
-    api_key : "<api_key>"
-    method :  "get_users_group"
-    args :    {
-                "group_name" : "<name>"
-              }
-
-OUTPUT::
-
-    result : None if group not exist
-             {
-               "id" :       "<id>",
-               "name" :     "<name>",
-               "active":    "<bool>",
-               "members" :  [
-	    	                  { "id" :       "<userid>",
-	                            "username" : "<username>",
-	                            "firstname": "<firstname>",
-	                            "lastname" : "<lastname>",
-	                            "email" :    "<email>",
-	                            "active" :   "<bool>",
-	                            "admin" :    "<bool>",
-	                            "ldap" :     "<ldap_dn>"
-	                          },
-	    	                  …
-	                        ]
-             }
-    error : null
 
 create_users_group
 ------------------
@@ -216,12 +293,13 @@
 Creates new users group. This command can be executed only using api_key
 belonging to user with admin rights
 
+
 INPUT::
 
     api_key : "<api_key>"
     method :  "create_users_group"
     args:     {
-                "name":  "<name>",
+                "group_name":  "<groupname>",
                 "active":"<bool> = True"
               }
 
@@ -229,39 +307,120 @@
 
     result: {
               "id":  "<newusersgroupid>",
-              "msg": "created new users group <name>"
+              "msg": "created new users group <groupname>"
             }
     error:  null
 
+
 add_user_to_users_group
 -----------------------
 
-Adds a user to a users group. This command can be executed only using api_key
+Adds a user to a users group. If user exists in that group success will be 
+`false`. This command can be executed only using api_key
 belonging to user with admin rights
 
+
 INPUT::
 
     api_key : "<api_key>"
     method :  "add_user_users_group"
     args:     {
                 "group_name" :  "<groupname>",
-                "user_name" :   "<username>"
+                "username" :   "<username>"
               }
 
 OUTPUT::
 
     result: {
               "id":  "<newusersgroupmemberid>",
-              "msg": "created new users group member"
+              "success": True|False # depends on if member is in group
+              "msg": "added member <username> to users group <groupname> | 
+                      User is already in that group"
+            }
+    error:  null
+
+
+remove_user_from_users_group
+----------------------------
+
+Removes a user from a users group. If user is not in given group success will
+be `false`. This command can be executed only 
+using api_key belonging to user with admin rights
+
+
+INPUT::
+
+    api_key : "<api_key>"
+    method :  "remove_user_from_users_group"
+    args:     {
+                "group_name" :  "<groupname>",
+                "username" :   "<username>"
+              }
+
+OUTPUT::
+
+    result: {
+              "success":  True|False,  # depends on if member is in group
+              "msg": "removed member <username> from users group <groupname> | 
+                      User wasn't in group"
             }
     error:  null
 
+
+get_repo
+--------
+
+Gets an existing repository by it's name or repository_id. This command can 
+be executed only using api_key belonging to user with admin rights.
+
+
+INPUT::
+
+    api_key : "<api_key>"
+    method :  "get_repo"
+    args:     {
+                "repoid" : "<reponame or repo_id>"
+              }
+
+OUTPUT::
+
+    result: None if repository does not exist or
+            {
+                "id" :          "<id>",
+                "repo_name" :   "<reponame>"
+                "type" :        "<type>",
+                "description" : "<description>",
+                "members" :     [
+                                  { "id" :         "<userid>",
+                                    "username" :   "<username>",
+                                    "firstname":   "<firstname>",
+                                    "lastname" :   "<lastname>",
+                                    "email" :      "<email>",
+                                    "active" :     "<bool>",
+                                    "admin" :      "<bool>",
+                                    "ldap" :       "<ldap_dn>",
+                                    "permission" : "repository.(read|write|admin)"
+                                  },
+                                  …
+                                  {
+                                    "id" :       "<usersgroupid>",
+                                    "name" :     "<usersgroupname>",
+                                    "active":    "<bool>",
+                                    "permission" : "repository.(read|write|admin)"
+                                  },
+                                  …
+                                ]
+            }
+    error:  null
+
+
 get_repos
 ---------
 
 Lists all existing repositories. This command can be executed only using api_key
 belonging to user with admin rights
 
+
 INPUT::
 
     api_key : "<api_key>"
@@ -273,7 +432,7 @@
     result: [
               {
                 "id" :          "<id>",
-                "name" :        "<name>"
+                "repo_name" :   "<reponame>"
                 "type" :        "<type>",
                 "description" : "<description>"
               },
@@ -281,51 +440,39 @@
             ]
     error:  null
 
-get_repo
---------
+
+get_repo_nodes
+--------------
 
-Gets an existing repository. This command can be executed only using api_key
-belonging to user with admin rights
+returns a list of nodes and it's children in a flat list for a given path 
+at given revision. It's possible to specify ret_type to show only `files` or 
+`dirs`. This command can be executed only using api_key belonging to user 
+with admin rights
+
 
 INPUT::
 
     api_key : "<api_key>"
-    method :  "get_repo"
+    method :  "get_repo_nodes"
     args:     {
-                "name" : "<name>"
+                "repo_name" : "<reponame>",
+                "revision"  : "<revision>",
+                "root_path" : "<root_path>",
+                "ret_type"  : "<ret_type>" = 'all'
               }
 
 OUTPUT::
 
-    result: None if repository not exist
-            {
-                "id" :          "<id>",
+    result: [
+              {
                 "name" :        "<name>"
                 "type" :        "<type>",
-                "description" : "<description>",
-                "members" :     [
-                                  { "id" :         "<userid>",
-	                                "username" :   "<username>",
-	                                "firstname":   "<firstname>",
-	                                "lastname" :   "<lastname>",
-	                                "email" :      "<email>",
-	                                "active" :     "<bool>",
-	                                "admin" :      "<bool>",
-	                                "ldap" :       "<ldap_dn>",
-	                                "permission" : "repository.(read|write|admin)"
-	                              },
-                                  …
-                                  {
-                                    "id" :       "<usersgroupid>",
-                                    "name" :     "<usersgroupname>",
-                                    "active":    "<bool>",
-                                    "permission" : "repository.(read|write|admin)"
-                                  },
-                                  …
-                                ]
-            }
+              },
+              …
+            ]
     error:  null
 
+
 create_repo
 -----------
 
@@ -335,58 +482,146 @@
 For example "foo/bar/baz" will create groups "foo", "bar" (with "foo" as parent),
 and create "baz" repository with "bar" as group.
 
+
 INPUT::
 
     api_key : "<api_key>"
     method :  "create_repo"
     args:     {
-                "name" :        "<name>",
+                "repo_name" :   "<reponame>",
                 "owner_name" :  "<ownername>",
                 "description" : "<description> = ''",
                 "repo_type" :   "<type> = 'hg'",
-                "private" :     "<bool> = False"
+                "private" :     "<bool> = False",
+                "clone_uri" :   "<clone_uri> = None",
               }
 
 OUTPUT::
 
-    result: None
+    result: {
+              "id": "<newrepoid>",
+              "msg": "Created new repository <reponame>",
+            }
     error:  null
 
-add_user_to_repo
-----------------
+
+delete_repo
+-----------
+
+Deletes a repository. This command can be executed only using api_key
+belonging to user with admin rights.
+
+
+INPUT::
+
+    api_key : "<api_key>"
+    method :  "delete_repo"
+    args:     {
+                "repo_name" :   "<reponame>",
+              }
 
-Add a user to a repository. This command can be executed only using api_key
-belonging to user with admin rights.
-If "perm" is None, user will be removed from the repository.
+OUTPUT::
+
+    result: {
+              "msg": "Deleted repository <reponame>",
+            }
+    error:  null
+
+
+grant_user_permission
+---------------------
+
+Grant permission for user on given repository, or update existing one
+if found. This command can be executed only using api_key belonging to user 
+with admin rights.
+
 
 INPUT::
 
     api_key : "<api_key>"
-    method :  "add_user_to_repo"
+    method :  "grant_user_permission"
     args:     {
                 "repo_name" :  "<reponame>",
-                "user_name" :  "<username>",
-                "perm" :       "(None|repository.(read|write|admin))",
+                "username" :   "<username>",
+                "perm" :       "(repository.(none|read|write|admin))",
+              }
+
+OUTPUT::
+
+    result: {
+              "msg" : "Granted perm: <perm> for user: <username> in repo: <reponame>"
+            }
+    error:  null
+
+
+revoke_user_permission
+----------------------
+
+Revoke permission for user on given repository. This command can be executed 
+only using api_key belonging to user with admin rights.
+
+
+INPUT::
+
+    api_key : "<api_key>"
+    method  : "revoke_user_permission"
+    args:     {
+                "repo_name" :  "<reponame>",
+                "username" :   "<username>",
               }
 
 OUTPUT::
 
-    result: None
+    result: {
+              "msg" : "Revoked perm for user: <suername> in repo: <reponame>"
+            }
     error:  null
 
-add_users_group_to_repo
------------------------
+
+grant_users_group_permission
+----------------------------
 
-Add a users group to a repository. This command can be executed only using 
-api_key belonging to user with admin rights. If "perm" is None, group will 
-be removed from the repository.
+Grant permission for users group on given repository, or update
+existing one if found. This command can be executed only using 
+api_key belonging to user with admin rights.
+
 
 INPUT::
 
     api_key : "<api_key>"
-    method :  "add_users_group_to_repo"
+    method :  "grant_users_group_permission"
+    args:     {
+                "repo_name" : "<reponame>",
+                "group_name" : "<usersgroupname>",
+                "perm" : "(repository.(none|read|write|admin))",
+              }
+
+OUTPUT::
+
+    result: {
+              "msg" : "Granted perm: <perm> for group: <usersgroupname> in repo: <reponame>"
+            }
+    error:  null
+    
+    
+revoke_users_group_permission
+-----------------------------
+
+Revoke permission for users group on given repository.This command can be 
+executed only using api_key belonging to user with admin rights.
+
+INPUT::
+
+    api_key : "<api_key>"
+    method  : "revoke_users_group_permission"
     args:     {
                 "repo_name" :  "<reponame>",
-                "group_name" :  "<groupname>",
-                "perm" :       "(None|repository.(read|write|admin))",
-              }
\ No newline at end of file
+                "users_group" :   "<usersgroupname>",
+              }
+
+OUTPUT::
+
+    result: {
+              "msg" : "Revoked perm for group: <usersgroupname> in repo: <reponame>"
+            }
+    error:  null
\ No newline at end of file