id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_ip"

    args :    {

                "userid" : "<user_id or username>",

              }

OUTPUT::

    id : <id_given_in_input>

    result : {

                 "user_ips": [

                                {

                                   "ip_addr": "<ip_with_mask>",

                                   "ip_range": ["<start_ip>", "<end_ip>"],

                                },

                                ...

                             ]

             }

    error :  null

get_user

    id : <id_given_in_input>

    result: None if user does not exist or

            {

                "user_id" :     "<user_id>",

                "api_key" :     "<api_key>",

                "username" :    "<username>",

                "firstname":    "<firstname>",

                "lastname" :    "<lastname>",

                "email" :       "<email>",

                "emails":       "<list_of_all_additional_emails>",

                "ip_addresses": "<list_of_ip_addresses_for_user>",

                "active" :      "<bool>",

                "ldap_dn" :     "<ldap_dn>",

                "last_login":   "<last_login>",

                "permissions": {

                    "global": ["hg.create.repository",

                               "repository.read",

                               "hg.register.manual_activate"],

                    "repositories": {"repo1": "repository.none"},

                    "repositories_groups": {"Group1": "group.read"}

                 },

            }

    error:  null

    id : <id_given_in_input>

    result: [

              {

                "user_id" :     "<user_id>",

                "api_key" :     "<api_key>",

                "username" :    "<username>",

                "firstname":    "<firstname>",

                "lastname" :    "<lastname>",

                "email" :       "<email>",

                "emails":       "<list_of_all_additional_emails>",

                "ip_addresses": "<list_of_ip_addresses_for_user>",

                "active" :      "<bool>",

                "ldap_dn" :     "<ldap_dn>",

                "last_login":   "<last_login>",

              },

              …

            ]

    error:  null

.. _create-user:

create_user

^^^^^^^^^^^

    id : <id_given_in_input>

    result: {

              "msg" : "created new user `<username>`",

              "user": {

                "user_id" :  "<user_id>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "emails":    "<list_of_all_additional_emails>",

                "active" :   "<bool>",

                "ldap_dn" :  "<ldap_dn>",

                "last_login": "<last_login>",

              },

            }

    error:  null

Example::

    kallithea-api create_user username:bent email:bent@example.com firstname:Bent lastname:Bentsen extern_type:ldap extern_name:uid=bent,dc=example,dc=com

update_user

^^^^^^^^^^^

    id : <id_given_in_input>

    result: {

              "msg" : "updated user ID:<userid> <username>",

              "user": {

                "user_id" :  "<user_id>",

                "api_key" :  "<api_key>",

                "username" : "<username>",

                "firstname": "<firstname>",

                "lastname" : "<lastname>",

                "email" :    "<email>",

                "emails":    "<list_of_all_additional_emails>",

                "active" :   "<bool>",

                "ldap_dn" :  "<ldap_dn>",

                "last_login": "<last_login>",

              },

            }

    error:  null

delete_user

^^^^^^^^^^^

Delete the given user if such a user exists.

This command can only be executed using the api_key of a user with admin rights.

               "group_name" :     "<groupname>",

               "active":          "<bool>",

               "members" :  [

                              {

                                "user_id" :  "<user_id>",

                                "api_key" :  "<api_key>",

                                "username" : "<username>",

                                "firstname": "<firstname>",

                                "lastname" : "<lastname>",

                                "email" :    "<email>",

                                "emails":    "<list_of_all_additional_emails>",

                                "active" :   "<bool>",

                                "ldap_dn" :  "<ldap_dn>",

                                "last_login": "<last_login>",

                              },

                              …

                            ]

             }

    error : null

get_user_groups

^^^^^^^^^^^^^^^

List all existing user groups.

                "fork_of":           "<name_of_fork_parent>",

                "members" :     [

                                  {

                                    "type":        "user",

                                    "user_id" :    "<user_id>",

                                    "api_key" :    "<api_key>",

                                    "username" :   "<username>",

                                    "firstname":   "<firstname>",

                                    "lastname" :   "<lastname>",

                                    "email" :      "<email>",

                                    "emails":      "<list_of_all_additional_emails>",

                                    "active" :     "<bool>",

                                    "ldap_dn" :    "<ldap_dn>",

                                    "last_login":  "<last_login>",

                                    "permission" : "repository.(read|write|admin)"

                                  },

                                  …

                                  {

                                    "type":      "users_group",

                                    "id" :       "<usersgroupid>",

                                    "name" :     "<usersgroupname>",

                                    "active":    "<bool>",

                                    "permission" : "repository.(read|write|admin)"

                                  },

                                ],

                 "followers":   [

                                  {

                                    "user_id" :     "<user_id>",

                                    "username" :    "<username>",

                                    "api_key" :     "<api_key>",

                                    "firstname":    "<firstname>",

                                    "lastname" :    "<lastname>",

                                    "email" :       "<email>",

                                    "emails":       "<list_of_all_additional_emails>",

                                    "ip_addresses": "<list_of_ip_addresses_for_user>",

                                    "active" :      "<bool>",

                                    "ldap_dn" :     "<ldap_dn>",

                                    "last_login":   "<last_login>",

                                  },

                                  …

                                ],

                 <if with_revision_names == True>

                 "tags": {

                            "<tagname>": "<raw_id>",

                            ...

                         },

                 "branches": {

                            "<branchname>": "<raw_id>",

                "end_date": "<date> = Optional(None)",      # in "%Y-%m-%dT%H:%M:%S" format

                "branch_name": "<branch name filter> = Optional(None)",

                "reverse": "<bool> = Optional(False)",

                "with_file_list": "<bool> = Optional(False)"

              }

OUTPUT::

    id : <id_given_in_input>

    result: [

    {

      "raw_id": "<raw_id>",

      "author": "<full_author>",

      "date": "<date_time_of_commit>",

      "message": "<commit_message>",

      "revision": "<numeric_revision>",

      <if with_file_list == True>

      "added": [<list of added files>],

      "changed": [<list of changed files>],

      "removed": [<list of removed files>]

    },

    ...

    ]

    error:  null

        defined IP addresses for given user. If userid is not passed data is

        returned for user who's calling this function.

        This command can be executed only using api_key belonging to user with

        admin rights.

        :param userid: username to show ips for

        :type userid: Optional(str or int)

        OUTPUT::

            id : <id_given_in_input>

            result : {

                         "user_ips": [

                                        {

                                           "ip_addr": "<ip_with_mask>",

                                           "ip_range": ["<start_ip>", "<end_ip>"],

                                        },

                                        ...

                                     ]

            }

        """

        if userid is None:

            userid = request.authuser.user_id

        user = get_user_or_error(userid)

        ips = db.UserIpMap.query().filter(db.UserIpMap.user == user).all()

        return dict(

            server_ip_addr=request.ip_addr,

            user_ips=ips

        )

    # alias for old

    show_ip = get_ip

        except Exception:

            log.error(traceback.format_exc())

            raise JSONRPCError('failed to delete user group ID:%s %s' %

                               (user_group.users_group_id,

                                user_group.users_group_name)

                               )

    # permission check inside

    def add_user_to_user_group(self, usergroupid, userid):

        """

        Adds a user to a user group. If user exists in that group success will be

        `false`. This command can be executed only using api_key

        :param usergroupid:

        :type usergroupid: str or int

        :param userid:

        :type userid: str or int

        OUTPUT::

          id : <id_given_in_input>

          result : {

              "success": True|False # depends on if member is in group

                      User is already in that group"

          }

          error :  null

        ERROR OUTPUT::

          id : <id_given_in_input>

          result : null

          error :  {

            "failed to add member to user group `<user_group_name>`"

          }

        Gets an existing repository by it's name or repository_id. Members will return

        either users_group or user associated to that repository. This command can be

        executed only using api_key belonging to user with admin

        rights or regular user that have at least read access to repository.

        :param repoid: repository name or repository id

        :type repoid: str or int

        OUTPUT::

          id : <id_given_in_input>

          result : {

                "repo_id" :          "<repo_id>",

                "repo_name" :        "<reponame>"

                "repo_type" :        "<repo_type>",

                "clone_uri" :        "<clone_uri>",

                "enable_downloads":  "<bool>",

                "enable_statistics": "<bool>",

                "private":           "<bool>",

                "created_on" :       "<date_time_created>",

                "description" :      "<description>",

                "landing_rev":       "<landing_rev>",

                "last_changeset":    {

                                       "author":   "<full_author>",

                 "tags": {

                            "<tagname>": "<raw_id>",

                            ...

                         },

                 "branches": {

                            "<branchname>": "<raw_id>",

                            ...

                         },

                 "bookmarks": {

                            "<bookmarkname>": "<raw_id>",

                            ...

                         },

          }

          error :  null

        """

        repo = get_repo_or_error(repoid)

        if not HasPermissionAny('hg.admin')():

            if not HasRepoPermissionLevel('read')(repo.repo_name):

                raise JSONRPCError('repository `%s` does not exist' % (repoid,))

        members = []

        for user in repo.repo_to_perm:

        admin, write or read access to repository.

        OUTPUT::

            id : <id_given_in_input>

            result: [

                      {

                        "repo_id" :          "<repo_id>",

                        "repo_name" :        "<reponame>"

                        "repo_type" :        "<repo_type>",

                        "clone_uri" :        "<clone_uri>",

                        "created_on" :       "<datetimecreated>",

                        "description" :      "<description>",

                        "landing_rev":       "<landing_rev>",

                        "owner":             "<repo_owner>",

                        "fork_of":           "<name_of_fork_parent>",

                        "enable_downloads":  "<bool>",

                        "enable_statistics": "<bool>",

                      },

                      …

                    ]

            error:  null

        """

        :type repoid: str or int

        :param fork_name:

        :param owner:

        :param description:

        :param copy_permissions:

        :param private:

        :param landing_rev:

        INPUT::

            id : <id_for_response>

            api_key : "<api_key>"

            args:     {

                        "repoid" :          "<reponame or repo_id>",

                        "fork_name":        "<forkname>",

                        "owner":            "<username or user_id = Optional(=apiuser)>",

                        "description":      "<description>",

                        "copy_permissions": "<bool>",

                        "private":          "<bool>",

                        "landing_rev":      "<landing_rev>"

                      }

        OUTPUT::