API

Starting from RhodeCode version 1.2 a simple API was implemented. There’s a single schema for calling all api methods. API is implemented with JSON protocol both ways. An url to send API request to RhodeCode is <your_server>/_admin/api

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. For example to access the raw diff:

http://<server>/<repo>/changeset-diff/<sha>?api_key=<key>

By default this is only 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

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 from remote repositories repos using curl::
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 those parameters:
  • 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

Note

api_key can be found under my account > auth token section. There’s always one autogenerated token per user. But for security reasons you should always create a dedicated token for API use only.

RhodeCode API will return always a JSON-RPC response:

{
    "id": <id>, # matching id sent by request
    "result": "<result>"|null, # JSON formatted result, null if any errors
    "error": "null"|<error_message> # JSON formatted error (if any)
}

All responses from API will be with HTTP/1.0 200 OK status code. In case there’s an error while calling api the error key from response will contain failure description and result key will be null.

API CLIENT

From version 1.4 RhodeCode adds a script that allows to easily communicate with API. After installing RhodeCode a rhodecode-api script will be available.

To get started quickly simply run:

rhodecode-api --save-config --apikey=<youapikey> --apihost=<rhodecode host>

This will create a file named .config in users HOME directory, storing json config file with credentials. You can skip this step and always provide both of the arguments to be able to communicate with server

after that simply run any api command for example get_repo:

rhodecode-api get_repo

Calling method get_repo => http://127.0.0.1:5000
Server response
"Missing non optional `repoid` arg in JSON DATA"

Ups looks like we forgot to add an argument

Let’s try again now giving the repoid as parameters:

rhodecode-api get_repo repoid:rhodecode

Calling method get_repo => http://127.0.0.1:5000
Server response
{
    <json data>
}

Optionally user can specify –format param to change the output to pure JSON:

rhodecode-api --format=json get_repo repoid:rhodecode

In such case only output that this function shows is pure JSON, we can use that and pip output to some json formatter:

rhodecode-api --format=json get_repo repoid:rhodecode | python -m json.tool

API METHODS

Each method by default required following arguments:

id :      "<id_for_response>"
api_key : "<api_key>"
method :  "<method name>"
args :    {}

Use each param from docs and put it in args, Optional parameters are not required in args:

args: {"repoid": "rhodecode"}

— API DEFS —

pull(apiuser, repoid)

This triggers a pull on the given repository from a remote location. Use this to keep remote repositories up-to-date.

Note

This command can only be run using an API_KEY with admin rights to the specified repository.

This command takes the following options:

Parameters:
  • apiuser (AuthUser.) – This is filled automatically from the API_KEY.
  • repoid (str or int.) – The repository name or repository id.

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "Pulled from `<repository name>`"
  "repository": "<repository name>"
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "Unable to pull changes from `<reponame>`"
}
strip(apiuser, repoid, revision, branch)

This command strips the given revision for the specified repository. It removes the revision and all of its ancestors. The branch parameter must be used for git compatibility.

Note

This command can only be run using an API_KEY with admin rights to the specified repository.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • revision (str) – revision to strip
  • branch (str) – branch to strip the revision, only applies to git really

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "'Stripped commit <commit_hash> from repo `<repository name>`'"
  "repository": "<repository name>"
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "Unable to strip commit <commit_hash> from repo `<repository name>`"
}
rescan_repos(apiuser, remove_obsolete=<Optional:False>)

This command triggers a rescan of the specified repositories. If the remove_obsolete option is set it also deletes repositories that are in the database but not in the file system, so called “clean zombies”.

Note

This command can only be run using an API_KEY with admin rights to the specified repository.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • remove_obsolete (Optional(True | False)) – Deletes repositories from the database not found on the filesystem

OUTPUT:

id : <id_given_in_input>
result : {
  'added': [<added repository name>,...]
  'removed': [<removed repository name>,...]
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  'Error occurred during rescan repositories action'
}
invalidate_cache(apiuser, repoid, delete_keys=<Optional:False>)

This command invalidates the cache for the specified repository.

Note

This command can only be run using an API_KEY with admin rights to the specified repository.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from API_KEY
  • repoid (str or int) – Sets the repository name or repository id
  • delete_keys – This deletes the invalidate keys instead of flagging them
Type:

Optional(True | False)

OUTPUT:

id : <id_given_in_input>
result : {
  'msg': Cache for repository `<repository name>` was invalidated,
  'repository': <repository name>
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  'Error occurred during cache invalidation action'
}
lock(apiuser, repoid, locked=<Optional:None>, userid=<Optional:<OptionalAttr:apiuser>>)

This command sets the locking state on the specified repository by the given user. If the userid option is not set, the repository is locked to the user who is calling the method. If the locked parameter is not set the current locked stated to the repository is displayed.

Note

This command can only be run using an API_KEY with admin rights to the specified repository.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • repoid (str or int) – Sets the repository name or repository id
  • locked (Optional(True | False)) – lock state to be set
  • userid (Optional(str or int)) – Set the repository lock to this user

OUTPUT:

id : <id_given_in_input>
result : {
  'repo': '<reponame>',
  'locked': <bool: lock state>,
  'locked_since': <int: lock timestamp>,
  'locked_by': <username of person who made the lock>,
  'lock_reason': <str: reason for locking>,
  'lock_state_changed': <bool: True if lock state has been changed in this request>,
  'msg': 'Repo `<reponame>` locked by `<username>` on <timestamp>.'
  or
  'msg': 'Repo `<repository name>` not locked.'
  or
  'msg': 'User `<user name>` set lock state for repo `<repository name>` to `<new lock state>`'
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  'Error occurred locking repository `<reponame>`
}
get_locks(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)

This command displays all the repositories the specified user has locked. If this command is run by a non-admin userid then it returns the list of locked repositories for that user.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • userid (Optional(str or int)) – Sets the userid to display their locked repositories

OUTPUT:

id : <id_given_in_input>
result : {
  [repo_object, repo_object,...]
}
error :  null
get_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)

This command displays the IP Address as seen from the RhodeCode server, along with all the defined IP addresses for the specified user. If the userid is not set the data returned is for the user salling the method.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from API_KEY
  • userid (Optional(str or int)) – Sets the userid for which associated IP Address data is returned

OUTPUT:

id : <id_given_in_input>
result : {
             "server_ip_addr": "<ip_from_clien>",
             "user_ips": [
                            {
                               "ip_addr": "<ip_with_mask>",
                               "ip_range": ["<start_ip>", "<end_ip>"],
                            },
                            ...
                         ]
}
show_ip(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)

This command displays the IP Address as seen from the RhodeCode server, along with all the defined IP addresses for the specified user. If the userid is not set the data returned is for the user salling the method.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from API_KEY
  • userid (Optional(str or int)) – Sets the userid for which associated IP Address data is returned

OUTPUT:

id : <id_given_in_input>
result : {
             "server_ip_addr": "<ip_from_clien>",
             "user_ips": [
                            {
                               "ip_addr": "<ip_with_mask>",
                               "ip_range": ["<start_ip>", "<end_ip>"],
                            },
                            ...
                         ]
}
get_server_info(apiuser)

This command returns the RhodeCode server information, including the running version of RhodeCode and all installed packages. This command takes the following options:

Parameters:apiuser (AuthUser) – This is filled automatically from the API_KEY

OUTPUT:

id : <id_given_in_input>
result : {
  'modules': [<module name>,...]
  'py_version': <python version>,
  'platform': <platform type>,
  'rhodecode_version': <rhodecode version>
}
error :  null
get_user(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)

This command returns the information associated with a username or userid. If the userid is not set the command returns the information for the userid calling the method.

Note

Normal users may only run this command against their userid. For full privileges you must run this command using an API_KEY with admin rights.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • userid (Optional(str or int)) – Sets the userid for which data will be returned.

OUTPUT:

id : <id_given_in_input>
result: None if user does not exist or
        {
            "user_id" :     "<user_id>",
            "api_key" :     "<api_key>",
            "api_keys":     "[<list of all api keys including additional ones>]"
            "username" :    "<username>",
            "firstname":    "<firstname>",
            "lastname" :    "<lastname>",
            "email" :       "<email>",
            "emails":       "[<list of all emails including additional ones>]",
            "ip_addresses": "[<ip_addresse_for_user>,...]",
            "active" :      "<bool: user active>",
            "admin" :       "<bool: user is admin>",
            "extern_name" : "<extern_name>",
            "extern_type" : "<extern type>
            "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
get_users(apiuser)

This command lists all users in the RhodeCode user database.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:apiuser (AuthUser) – This is filled automatically from the API_KEY

OUTPUT:

id : <id_given_in_input>
result: [<user_object>, ...]
error:  null
create_user(apiuser, username, email, password=<Optional:''>, firstname=<Optional:''>, lastname=<Optional:''>, active=<Optional:True>, admin=<Optional:False>, extern_name=<Optional:'rhodecode'>, extern_type=<Optional:'rhodecode'>, force_password_change=<Optional:False>)

This command creates a new user and returns the new user object.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • username (str or int) – Set the new username
  • email (str) – Set the user email address
  • password (Optional(str)) – Set the new user password
  • firstname (Optional(str)) – Set the new user firstname
  • lastname (Optional(str)) – Set the new user surname
  • active (Optional(True | False)) – Set the user as active
  • admin (Optional(True | False)) – Give the new user admin right
  • extern_name (Optional(str)) – Set the authentication plugin name. Using LDAP this is filled with LDAP UID
  • extern_type (Optional(str)) – Set the new user authentication plugin
  • force_password_change (Optional(True | False)) – Force the new user to change password on next login

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "created new user `<username>`",
          "user": <user_obj>
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "user `<username>` already exist"
  or
  "email `<email>` already exist"
  or
  "failed to create user `<username>`"
}
update_user(apiuser, userid, username=<Optional:None>, email=<Optional:None>, password=<Optional:None>, firstname=<Optional:None>, lastname=<Optional:None>, active=<Optional:None>, admin=<Optional:None>, extern_type=<Optional:None>, extern_name=<Optional:None>)

This command updates the details for the specified user, if that user exists.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from API_KEY
  • userid (str or int) – Set the userid to update
  • username (str or int) – Set the new username
  • email (str) – Set the new email
  • password (Optional(str)) – Set the new password
  • firstname (Optional(str)) – Set the new first name
  • lastname (Optional(str)) – Set the new surname
  • active (Optional(True | False)) – Set the new user as active
  • admin (Optional(True | False)) – Give the user admin rights
  • extern_name (Optional(str)) – Set the authentication plugin user name. Using LDAP this is filled with LDAP UID.
  • extern_type (Optional(str)) – Set the authentication plugin type.

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "updated user ID:<userid> <username>",
          "user": <user_object>,
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to update user `<username>`"
}
delete_user(apiuser, userid)

This command deletes the specified user from the RhodeCode user database.

Note

This command can only be run using an API_KEY with admin rights. Also, please ensure all open pull requests, open code reviews, and repositories, or repository groups owned by this are closed of reassigned before deletion.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • userid (str or int) – Set the user to delete

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "deleted user ID:<userid> <username>",
          "user": null
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to delete user ID:<userid> <username>"
}
get_user_group(apiuser, usergroupid)

This command gets the data of an existing user group.

Note

This command can only be run using an API_KEY with admin rights or read access to the user group specified.

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • usergroupid (str or int) – Set the id of the user_group to edit

OUTPUT:

id : <id_given_in_input>
result : None if group not exist
 {
    "users_group_id" : "<id>",
    "group_name" :     "<groupname>",
    "active":          "<bool>",
    "users" :  [<user_obj>,...],
    "members" : [
                  {
                    "name":        "<username>",
                    "permission" : "usergroup.(read|write|admin)",
                    "origin":      "<permission|owner|super-admin>",
                    "type" :       "user",
                  },
                  ...
                  {
                    "name":        "<usergroup name>",
                    "permission" : "usergroup.(read|write|admin)",
                    "origin":      "<permission|owner|super-admin>",
                    "type" :       "user",
                  },
                ...
    ]
 }
error : null
get_user_groups(apiuser)

This command lists all the existing user groups within RhodeCode.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:apiuser (AuthUser) – filled automatically from apikey

OUTPUT:

id : <id_given_in_input>
result : [<user_group_obj>,...]
error : null
create_user_group(apiuser, group_name, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, active=<Optional:True>)

This command creates a new user group.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • group_name (str) – Set the name of the new user group
  • description (str) – Give a description of the new user group
  • owner (Optional(str or int)) – Set the owner of the new user group. If not set, the owner is the API_KEY user
  • active (Optional(True | False)) – Set this group as active

OUTPUT:

id : <id_given_in_input>
result: {
          "msg": "created new user group `<groupname>`",
          "user_group": <user_group_object>
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "user group `<group name>` already exist"
  or
  "failed to create group `<group name>`"
}
update_user_group(apiuser, usergroupid, group_name=<Optional:''>, description=<Optional:''>, owner=<Optional:None>, active=<Optional:True>)

This command updates the specified user group with the details provided.

Note

This command can only be run using an API_KEY with admin rights.

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • usergroupid (str or int) – Set the id of the user group to update
  • group_name (str) – Set the new name the user group
  • description (str) – Give a description for the user group
  • owner (Optional(str or int)) – set the owner of the user group
  • active (Optional(True | False)) – Set the group as active

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": 'updated user group ID:<user group id> <user group name>',
  "user_group": <user_group_object>
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to update user group `<user group name>`"
}
delete_user_group(apiuser, usergroupid)

This command deletes the specified user group.

Note

This command can only be run using an API_KEY with admin rights.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • usergroupid (int) –

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "deleted user group ID:<user_group_id> <user_group_name>"
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to delete user group ID:<user_group_id> <user_group_name>"
  or
  "RepoGroup assigned to <repo_groups_list>"
}
add_user_to_user_group(apiuser, usergroupid, userid)

This command adds a user to a user group. If the user already exists in the group this command will return false.

Note

This command can only be run using an API_KEY with RhodeCode admin rights, or admin rights to the user group.

This command takes the following options:

Parameters:
  • apiuser (AuthUser) – This is filled automatically from the API_KEY
  • usergroupid (int) – Set the name of the user group to which a user will be added.
  • userid (int) – Set the user_id of the user to add

OUTPUT:

id : <id_given_in_input>
result : {
    "success": True|False # depends on if member is in group
    "msg": "added member `<username>` to user group `<groupname>` |
            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>`"
}
remove_user_from_user_group(apiuser, usergroupid, userid)

Removes a user from a user 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 or an admin of given user group

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • usergroupid (str or int) –
  • userid (str or int) – user which we want to remove

OUTPUT:

id : <id_given_in_input>
result: {
          "success":  True|False,  # depends on if member is in group
          "msg": "removed member <username> from user group <groupname> |
                  User wasn't in group"
        }
error:  null
grant_user_permission_to_user_group(apiuser, usergroupid, userid, perm)
Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • usergroupid (str or int) – user group that we perform operation on
  • userid –
  • perm (str) – (usergroup.(none|read|write|admin))

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "Granted perm: `<perm_name>` for user: `<username>` in user group: `<user_group_name>`",
  "success": true
}
error :  null
revoke_user_permission_from_user_group(apiuser, usergroupid, userid)
Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • usergroupid – user group that we perform operation on
  • userid –
Type:

usergroupid: str or int

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "Revoked perm for user: `<username>` in user group: `<user_group_name>`",
  "success": true
}
error :  null
grant_user_group_permission_to_user_group(apiuser, usergroupid, sourceusergroupid, perm)
Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • usergroupid – user group that we perform operation on
  • sourceusergroupid (str or int) – the source group we add as permission
  • perm (str) – (usergroup.(none|read|write|admin))
Type:

usergroupid: str or int

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "Granted perm: `<perm_name>` for user group: `<source_user_group_name>` in user group: `<user_group_name>`",
  "success": true
}
error :  null
revoke_user_group_permission_from_user_group(apiuser, usergroupid, sourceusergroupid)
Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • usergroupid – user group that we perform operation on
  • sourceusergroupid (str or int) – the source group we add as permission
Type:

usergroupid: str or int

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "Revoked perm for user group: `<user_group_name>` in user group: `<target_user_group_name>`",
  "success": true
}
error :  null
get_repo(apiuser, repoid, cache=<Optional:True>)

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.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • cache – use the cached value for last changeset
Type:

cache: Optional(bool)

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_locking":    "<bool>",
      "enable_statistics": "<bool>",
      "private":           "<bool>",
      "created_on" :       "<date_time_created>",
      "description" :      "<description>",
      "landing_rev":       "<landing_rev>",
      "last_changeset":    {
                             "author":   "<full_author>",
                             "date":     "<date_time_of_commit>",
                             "message":  "<commit_message>",
                             "raw_id":   "<raw_id>",
                             "revision": "<numeric_revision>",
                             "short_id": "<short_id>"
                           }
      "owner":             "<repo_owner>",
      "fork_of":           "<name_of_fork_parent>",
      "members" :     [
                        {
                          "name":        "<username>",
                          "permission" : "repository.(read|write|admin)",
                          "origin":      "<permission|owner|super-admin>",
                          "type" :       "user",
                        },
                        ...
                        {
                          "name":        "<usergroup name>",
                          "permission" : "repository.(read|write|admin)",
                          "origin":      "<permission|owner|super-admin>",
                          "type" :       "user",
                        },
                        ...
                      ]
       "followers":   [<user_obj>, ...]
       ]
  }
error :  null
get_repos(apiuser)

Lists all existing repositories. This command can be executed only using api_key belonging to user with admin rights or regular user that have admin, write or read access to repository.

Parameters:apiuser (AuthUser) – filled automatically from apikey

OUTPUT:

id : <id_given_in_input>
result: [
          {
            "repo_id" :          "<repo_id>",
            "repo_name" :        "<reponame>"
            "repo_type" :        "<repo_type>",
            "clone_uri" :        "<clone_uri>",
            "private": :         "<bool>",
            "created_on" :       "<datetimecreated>",
            "description" :      "<description>",
            "landing_rev":       "<landing_rev>",
            "owner":             "<repo_owner>",
            "fork_of":           "<name_of_fork_parent>",
            "enable_downloads":  "<bool>",
            "enable_locking":    "<bool>",
            "enable_statistics": "<bool>",
          },
          ...
        ]
error:  null
get_repo_changeset(apiuser, repoid, revision, details=<Optional:'basic'>)

returns information about changeset. Additionally detail params defines the ammount of details returned by this function. 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.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • revision (str) – revision for which listing should be done
  • details (Optional(str)) – details can be ‘basic|extended|full’ full gives diff info details like the diff itself, and number of changed files etc.
get_repo_changesets(apiuser, repoid, start_rev, limit, details=<Optional:'basic'>)

returns set of changesets limited by the number of commits starting from start_rev. Additionally detail params defines the amount of details returned by this function. 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.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • start_rev (str) – starting revision to get changesets from
  • limit (str or int) – limit the number of changesets to this amount
  • details (Optional(str)) – details can be ‘basic|extended|full’ full gives diff info details like the diff itself, and number of changed files etc.
get_repo_nodes(apiuser, repoid, revision, root_path, ret_type=<Optional:'all'>, details=<Optional:'basic'>)

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 or regular user that have at least read access to repository.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • revision (str) – revision for which listing should be done
  • root_path (str) – path from which start displaying
  • ret_type (Optional(str)) – return type ‘all|files|dirs’ nodes
  • details (Optional(str) ‘basic|full’) – return extended information about nodes (md5, binary, and or content)

OUTPUT:

id : <id_given_in_input>
result: [
          {
            "name" : "<name>"
            "type" : "<type>",
            "binary": "<true|false>" (only in extended mode)
            "md5"  : "<md5 of file content>" (only in extended mode)
          },
          ...
        ]
error:  null
create_repo(apiuser, repo_name, repo_type, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, copy_permissions=<Optional:False>)

Creates a repository. If repository name contains “/”, all needed repository groups will be created. For example “foo/bar/baz” will create groups “foo”, “bar” (with “foo” as parent), and create “baz” repository with “bar” as group. This command can be executed only using api_key belonging to user with admin rights or regular user that have create repository permission. Regular users cannot specify owner parameter

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repo_name (str) – repository name
  • repo_type (str) – repository type ‘hg’,’git’,’svn’
  • owner (Optional(str)) – user_id or username
  • description (Optional(str)) – repository description
  • private (bool) –
  • clone_uri (str) –
  • landing_rev (str) – <rev_type>:<rev>
  • enable_locking (bool) –
  • enable_downloads (bool) –
  • enable_statistics (bool) –
  • copy_permissions (bool) – Copy permission from group that repository is being created.

OUTPUT:

id : <id_given_in_input>
result: {
          "msg": "Created new repository `<reponame>`",
          "success": true,
          "task": "<celery task id or None if done sync>"
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
   'failed to create repository `<repo_name>`
}
add_field_to_repo(apiuser, repoid, key, label=<Optional:''>, description=<Optional:''>)

Add extra field to a repository.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • key (str) – unique field key for this repository
  • label (Optional(str)) –
  • description (Optional(str)) –
remove_field_from_repo(apiuser, repoid, key)

Remove extra field from a repository. This command can be executed only using api_key belonging to user with admin rights or regular user that have admin access to repository.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • key (str) – unique field key for this repository
update_repo(apiuser, repoid, name=<Optional:None>, owner=<Optional:<OptionalAttr:apiuser>>, group=<Optional:None>, description=<Optional:''>, private=<Optional:False>, clone_uri=<Optional:None>, landing_rev=<Optional:'rev:tip'>, enable_statistics=<Optional:False>, enable_locking=<Optional:False>, enable_downloads=<Optional:False>, fields=<Optional:''>)

Update repository. This command can be executed only using api_key belonging to user with admin rights or regular user that have admin access to repository.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • name –
  • owner –
  • group –
  • description (str) –
  • private (bool) –
  • clone_uri (str) –
  • landing_rev (str) –
  • enable_statistics (bool) –
  • enable_locking (bool) –
  • enable_downloads (bool) –
  • fields – extra fields, in format of fields:field_key=field_val,field_key2=fieldval2. Escape ‘,’ with ,
fork_repo(apiuser, repoid, fork_name, owner=<Optional:<OptionalAttr:apiuser>>, description=<Optional:''>, copy_permissions=<Optional:False>, private=<Optional:False>, landing_rev=<Optional:'rev:tip'>)

Creates a fork of given repo. In case of using celery this will immediately return success message, while fork is going to be created asynchronous. This command can be executed only using api_key belonging to user with admin rights or regular user that have fork permission, and at least read access to forking repository. Regular users cannot specify owner parameter.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • fork_name –
  • owner –
  • description –
  • copy_permissions –
  • private –
  • 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:

id : <id_given_in_input>
result: {
          "msg": "Created fork of `<reponame>` as `<forkname>`",
          "success": true,
          "task": "<celery task id or None if done sync>"
        }
error:  null
delete_repo(apiuser, repoid, forks=<Optional:''>)

Deletes a repository. This command can be executed only using api_key belonging to user with admin rights or regular user that have admin access to repository. When forks param is set it’s possible to detach or delete forks of deleting repository

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • forks (Optional(str)) – detach or delete, what do do with attached forks for repo

OUTPUT:

id : <id_given_in_input>
result: {
          "msg": "Deleted repository `<reponame>`",
          "success": true
        }
error:  null
changeset_comment(apiuser, repoid, revision, message, userid=<Optional:<OptionalAttr:apiuser>>, status=<Optional:None>)

Set changeset comment, and optionally change status of the changeset. This command can be executed only using api_key belonging to user with admin rights, or repository administrator.

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "Commented on revision `<revision>` for repo `<repoid>`",
  "status_change": null or <status>,
  "success": true
}
error :  null
Parameters:
  • apiuser (AuthUser) –
  • repoid (str or int) – repository name or repository id
  • revision (str) – revision to set the comment for
  • message (str) – message
  • userid (Optional(str or int)) – optionally an user to make this comment as.
  • status (str) – status, one of ‘not_reviewed’, ‘approved’, ‘rejected’, ‘under_review’
grant_user_permission(apiuser, repoid, userid, perm)

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, or repository administrator.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • userid –
  • perm (str) – (repository.(none|read|write|admin))

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
          "success": true
        }
error:  null
revoke_user_permission(apiuser, repoid, userid)

Revoke permission for user on given repository. This command can be executed only using api_key belonging to user with admin rights, or repository administrator.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • userid (str or int) –

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
          "success": true
        }
error:  null
grant_user_group_permission(apiuser, repoid, usergroupid, perm)

Grant permission for user 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, or repository administrator.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • usergroupid (str or int) – id of usergroup
  • perm (str) – (repository.(none|read|write|admin))

OUTPUT:

id : <id_given_in_input>
result : {
  "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
  "success": true

}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to edit permission for user group: `<usergroup>` in repo `<repo>`'
}
revoke_user_group_permission(apiuser, repoid, usergroupid)

Revoke permission for user group on given repository. This command can be executed only using api_key belonging to user with admin rights, or repository administrator.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repoid (str or int) – repository name or repository id
  • usergroupid –

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",
          "success": true
        }
error:  null
get_repo_group(apiuser, repogroupid)

Returns given repo group together with permissions, and repositories inside the group

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repogroupid (str or int) – id/name of repository group

OUTPUT:

id : <id_given_in_input>
result : None if group does not exist
    {
        "group_description": "<group_description>",
        "group_id": <group_id>,
        "group_name": "<group_name>",
        "members" : [
              {
                "name":        "<username>",
                "permission" : "group.(read|write|admin)",
                "origin":      "<permission|owner|super-admin>",
                "type" :       "user",
              },
              ...
              {
                "name":        "<usergroup name>",
                "permission" : "group.(read|write|admin)",
                "origin":      "<permission|owner|super-admin>",
                "type" :       "user",
              },
              ...
        ],
        "owner": "<group_onwer_username>",
        "parent_group": null,
        "repositories": [
            <repo_name>,
            ...
        ]
    }
error : null
get_repo_groups(apiuser)
Returns all repository groups
Parameters:apiuser (AuthUser) – filled automatically from apikey
create_repo_group(apiuser, group_name, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, copy_permissions=<Optional:False>)

Creates a repository group. Group name can have / in group_name. For example “foo/bar/baz” will create group baz, with foo/bar as parent This command can be executed only using api_key belonging to user with admin rights or user who has create repogroup permission

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • group_name (str) – repository group name
  • description –
  • owner –
  • copy_permissions –

OUTPUT:

id : <id_given_in_input>
result : {
    "msg": "Created new repo group `<repo_group_name>`"
    "repo_group": <repogroup_object>
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  failed to create repo group `<repogroupid>`
}
update_repo_group(apiuser, repogroupid, group_name=<Optional:''>, description=<Optional:''>, owner=<Optional:<OptionalAttr:apiuser>>, parent=<Optional:None>, enable_locking=<Optional:False>)

Updates repository group. This command can be executed only using api_key belonging to user with admin rights.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repogroupid (str or int) – name or id of repository group
  • group_name –
  • description –
  • owner –
  • parent –
  • enable_locking –
grant_user_permission_to_repo_group(apiuser, repogroupid, userid, perm, apply_to_children=<Optional:'none'>)

Grant permission for user on given repository group, or update existing one if found. This command can be executed only using api_key belonging to user with admin rights, or user who has admin right to given repository group.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repogroupid (str or int) – name or id of repository group
  • userid –
  • perm (str) – (group.(none|read|write|admin))
  • apply_to_children (str) – ‘none’, ‘repos’, ‘groups’, ‘all’

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",
          "success": true
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"
}
revoke_user_permission_from_repo_group(apiuser, repogroupid, userid, apply_to_children=<Optional:'none'>)

Revoke permission for user on given repository group. This command can be executed only using api_key belonging to user with admin rights, or user who has admin right to given repository group.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repogroupid (str or int) – name or id of repository group
  • userid –
  • apply_to_children (str) – ‘none’, ‘repos’, ‘groups’, ‘all’

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "Revoked perm (recursive:<apply_to_children>) for user: `<username>` in repo group: `<repo_group_name>`",
          "success": true
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to edit permission for user: `<userid>` in repo group: `<repo_group_name>`"
}
grant_user_group_permission_to_repo_group(apiuser, repogroupid, usergroupid, perm, apply_to_children=<Optional:'none'>)

Grant permission for user group on given repository group, or update existing one if found. This command can be executed only using api_key belonging to user with admin rights, or user who has admin right to given repository group.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repogroupid (str or int) – name or id of repository group
  • usergroupid (str or int) – id of usergroup
  • perm (str) – (group.(none|read|write|admin))
  • apply_to_children (str) – ‘none’, ‘repos’, ‘groups’, ‘all’

OUTPUT:

id : <id_given_in_input>
result : {
  "msg" : "Granted perm: `<perm>` (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",
  "success": true

}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to edit permission for user group: `<usergroup>` in repo group: `<repo_group_name>`"
}
revoke_user_group_permission_from_repo_group(apiuser, repogroupid, usergroupid, apply_to_children=<Optional:'none'>)

Revoke permission for user group on given repository. This command can be executed only using api_key belonging to user with admin rights, or user who has admin right to given repository group.

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • repogroupid (str or int) – name or id of repository group
  • usergroupid –
  • apply_to_children (str) – ‘none’, ‘repos’, ‘groups’, ‘all’

OUTPUT:

id : <id_given_in_input>
result: {
          "msg" : "Revoked perm (recursive:<apply_to_children>) for user group: `<usersgroupname>` in repo group: `<repo_group_name>`",
          "success": true
        }
error:  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to edit permission for user group: `<usergroup>` in repo group: `<repo_group_name>`"
}
get_gist(apiuser, gistid, content=<Optional:False>)

Get given gist by id

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • gistid (str) – id of private or public gist
  • content (Optional(bool)) – return content of stored files of gist
get_gists(apiuser, userid=<Optional:<OptionalAttr:apiuser>>)

Get all gists for given user. If userid is empty returned gists are for user who called the api

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • userid (Optional(str or int)) – user to get gists for
create_gist(apiuser, files, owner=<Optional:<OptionalAttr:apiuser>>, gist_type=<Optional:u'public'>, lifetime=<Optional:-1>, description=<Optional:''>)

Creates new Gist

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • files (dict) –

    files to be added to gist {‘filename’: {‘content’:’...’, ‘lexer’: null},

    ‘filename2’: {‘content’:’...’, ‘lexer’: null}}
  • owner (Optional(str or int)) – gist owner, defaults to api method caller
  • gist_type (Optional(str)) – type of gist ‘public’ or ‘private’
  • lifetime (Optional(int)) – time in minutes of gist lifetime
  • description (Optional(str)) – gist description

OUTPUT:

id : <id_given_in_input>
result : {
  "msg": "created new gist",
  "gist": {}
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to create gist"
}
delete_gist(apiuser, gistid)

Deletes existing gist

Parameters:
  • apiuser (AuthUser) – filled automatically from apikey
  • gistid (str) – id of gist to delete

OUTPUT:

id : <id_given_in_input>
result : {
  "deleted gist ID: <gist_id>",
  "gist": null
}
error :  null

ERROR OUTPUT:

id : <id_given_in_input>
result : null
error :  {
  "failed to delete gist ID:<gist_id>"
}