.. _api:

===

API

===

Kallithea has a simple JSON RPC API with a single schema for calling all API

methods. Everything is available by sending JSON encoded http(s) requests to

``<your_server>/_admin/api``.

API access

----------

Clients must send JSON encoded JSON-RPC requests::

    {

        "id: "<id>",

        "api_key": "<api_key>",

        "method": "<method_name>",

        "args": {"<arg_key>": "<arg_val>"}

    }

For example, to pull to a local "CPython" mirror using curl::

    curl https://kallithea.example.com/_admin/api -X POST -H 'content-type:text/plain' \

        --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

In general, provide

 - *id*, a value of any type, can be used to match the response with the request that it is replying to.

 - *api_key*, for authentication and permission validation.

 - *method*, the name of the method to call -- a list of available methods can be found below.

 - *args*, the arguments to pass to the method.

.. note::

    api_key can be found or set on the user account page.

The response to the JSON-RPC API call will always be a JSON structure::

    {

        "id": <id>,  # the id that was used in the request

        "result": <result>|null,  # JSON formatted result (null on error)

        "error": null|<error_message>  # JSON formatted error (null on success)

    }

All responses from the API will be ``HTTP/1.0 200 OK``. If an error occurs,

the reponse will have a failure description in *error* and

*result* will be null.

API client

----------

Kallithea comes with a ``kallithea-api`` command line tool, providing a convenient

way to call the JSON-RPC API.

For example, to call ``get_repo``::

    kallithea-api --apihost=<Kallithea URL> --apikey=<API key> get_repo

    Calling method get_repo => <Kallithea URL>

    Server response

    ERROR:"Missing non optional `repoid` arg in JSON DATA"

Oops, looks like we forgot to add an argument. Let's try again, now

providing the ``repoid`` as a parameter::

    kallithea-api --apihost=<Kallithea URL> --apikey=<API key> get_repo repoid:myrepo

    Calling method get_repo => <Kallithea URL>

    Server response

    {

        "clone_uri": null,

        "created_on": "2015-08-31T14:55:19.042",

    ...

To avoid specifying ``apihost`` and ``apikey`` every time, run::

    kallithea-api --save-config --apihost=<Kallithea URL> --apikey=<API key>

This will create a ``~/.config/kallithea`` with the specified URL and API key

so you don't have to specify them every time.

API methods

-----------

pull

^^^^

Pull the given repo from remote location. Can be used to automatically keep

remote repos up to date.

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "pull"

    args :    {

                "repoid" : "<reponame or repo_id>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : "Pulled from `<reponame>`"

    error :  null

rescan_repos

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

Rescan repositories. If ``remove_obsolete`` is set,

Kallithea will delete repos that are in the database but not in the filesystem.

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "rescan_repos"

    args :    {

                "remove_obsolete" : "<boolean = Optional(False)>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : "{'added': [<list of names of added repos>],

               'removed': [<list of names of removed repos>]}"

    error :  null

invalidate_cache

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

Invalidate the cache for a repository.

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

or that of a regular user with admin or write access to the repository.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "invalidate_cache"

    args :    {

                "repoid" : "<reponame or repo_id>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : "Caches of repository `<reponame>`"

    error :  null

lock

^^^^

Set the locking state on the given repository by the given user.

If the param ``userid`` is skipped, it is set to the ID of the user who is calling this method.

If param ``locked`` is skipped, the current lock state of the repository is returned.

This command can only be executed using the api_key of a user with admin rights, or that of a regular user with admin or write access to the repository.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "lock"

    args :    {

                "repoid" : "<reponame or repo_id>"

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

                "locked" : "<bool true|false = Optional(=None)>"

              }

OUTPUT::

    id : <id_given_in_input>

    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

get_ip

^^^^^^

Return IP address as seen from Kallithea server, together with all

defined IP addresses for given user.

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_ip"

    args :    {

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

              }

                "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":             "<username or user_id>",

                "fork_of":           "<name_of_fork_parent>",

                "enable_downloads":  "<bool>",

                "enable_locking":    "<bool>",

                "enable_statistics": "<bool>",

                "last_changeset":    {

                                       "author":   "<full_author>",

                                       "date":     "<date_time_of_commit>",

                                       "message":  "<commit_message>",

                                       "raw_id":   "<raw_id>",

                                       "revision": "<numeric_revision>",

                                       "short_id": "<short_id>"

                                     }

                "locked_by": "<username>",

                "locked_date": "<float lock_time>",

              },

            }

    error:  null

fork_repo

^^^^^^^^^

Create a fork of the given repo. If using Celery, this will

return success message immediately and a fork will be created

asynchronously.

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

rights, or with the global fork permission, by a regular user with create

repository permission and at least read access to the repository.

Regular users cannot specify owner parameter.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "fork_repo"

    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

            }

    error:  null

delete_repo

^^^^^^^^^^^

Delete a repository.

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

or that of a regular user with admin access to the repository.

When ``forks`` param is set it is possible to detach or delete forks of the deleted repository.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "delete_repo"

    args:     {

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

                "forks"  : "`delete` or `detach` = Optional(None)"

              }

OUTPUT::

    id : <id_given_in_input>

    result: {

              "msg": "Deleted repository `<reponame>`",

              "success": true

            }

    error:  null

grant_user_permission

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

Grant permission for a user on the given repository, or update the existing one if found.

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "grant_user_permission"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "userid" : "<username or user_id>"

                "perm" :       "(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

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

Revoke permission for a user on the given repository.

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method  : "revoke_user_permission"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "userid" : "<username or user_id>"

              }

OUTPUT::

    id : <id_given_in_input>

    result: {

              "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",

              "success": true

            }

    error:  null

grant_user_group_permission

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

Grant permission for a user group on the given repository, or update the

existing one if found.

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "grant_user_group_permission"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "usersgroupid" : "<user group id or name>"

                "perm" : "(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

revoke_user_group_permission

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

Revoke permission for a user group on the given repository.

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method  : "revoke_user_group_permission"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "usersgroupid" : "<user group id or name>"

              }

OUTPUT::

    id : <id_given_in_input>

    result: {

              "msg" : "Revoked perm for group: `<usersgroupname>` in repo: `<reponame>`",

              "success": true

            }

    error:  null