.. _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 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::

    {

        "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' \

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",