===

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 keys

--------

Every Kallithea user automatically receives an API key, which they can

view under "My Account". On this page, API keys can also be revoked, and

additional API keys can be generated.

API access

----------

Clients must send JSON encoded JSON-RPC requests::

    {

        "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":{"repoid":"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

    api_key : "<api_key>"

    method :  "create_user_group"

    args :    {

                "group_name": "<groupname>",

                "owner" :     "<owner_name_or_id = Optional(=apiuser)>",

                "active" :    "<bool> = Optional(True)"

              }

OUTPUT::

    id : <id_given_in_input>

    result : {

              "msg" : "created new user group `<groupname>`",

              "users_group" : {

                     "users_group_id" : "<id>",

                     "group_name" :     "<groupname>",

                     "active" :         "<bool>"

               }

             }

    error : null

add_user_to_user_group

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

``false``.

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 :  "add_user_user_group"

    args :    {

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

                "userid" : "<user_id or username>"

              }

OUTPUT::

    id : <id_given_in_input>

    result : {

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

              "msg" : "added member `<username>` to a user group `<groupname>` |

                       User is already in that group"

             }

    error : null

remove_user_from_user_group