.. _api:
API (Restfull/JSON) documentation
=================================
This documentation describes the Glances API version 4 (Restfull/JSON) interface.
For Glances version 3, please have a look on:
``https://github.com/nicolargo/glances/blob/support/glancesv3/docs/api.rst``
Run the Glances API server
--------------------------
The Glances Restfull/API server could be ran using the following command line:
.. code-block:: bash
# glances -w --disable-webui
It is also ran automatically when Glances is started in Web server mode (-w).
API URL
-------
The default root API URL is ``http://localhost:61208/api/4``.
The bind address and port could be changed using the ``--bind`` and ``--port`` command line options.
It is also possible to define an URL prefix using the ``url_prefix`` option from the [outputs] section
of the Glances configuration file.
Note: The url_prefix should always end with a slash (``/``).
For example:
.. code-block:: ini
[outputs]
url_prefix = /glances/
will change the root API URL to ``http://localhost:61208/glances/api/4`` and the Web UI URL to
``http://localhost:61208/glances/``
API documentation URL
---------------------
The API documentation is embeded in the server and available at the following URL:
``http://localhost:61208/docs#/``.
WebUI refresh
-------------
It is possible to change the Web UI refresh rate (default is 2 seconds) using the following option in the URL:
``http://localhost:61208/glances/?refresh=5``
GET API status
--------------
This entry point should be used to check the API status.
It will the Glances version and a 200 return code if everything is OK.
Get the Rest API status::
# curl -I http://localhost:61208/api/4/status
"HTTP/1.0 200 OK"
GET plugins list
----------------
Get the plugins list::
# curl http://localhost:61208/api/4/pluginslist
["alert",
"amps",
"cloud",
"connections",
"containers",
"core",
"cpu",
"diskio",
"folders",
"fs",
"gpu",
"help",
"ip",
"irq",
"load",
"mem",
"memswap",
"network",
"now",
"percpu",
"ports",
"processcount",
"processlist",
"psutilversion",
"quicklook",
"raid",
"sensors",
"smart",
"system",
"uptime",
"version",
"wifi"]
GET amps
--------
Get plugin stats::
# curl http://localhost:61208/api/4/amps
[{"count": 0,
"countmax": None,
"countmin": 1.0,
"key": "name",
"name": "Dropbox",
"refresh": 3.0,
"regex": True,
"result": None,
"timer": 0.3882608413696289},
{"count": 0,
"countmax": 20.0,
"countmin": None,
"key": "name",