JSON-RPC API (Obsolete)

From OpenCog

Warning, this page is out of date, see Web Interface for a current RESTful/JSON approach

This page outlines the specifications for a JSON-RPC interface for OpenCog (Launchpad blueprint here).


From wikipedia:

JSON-RPC is is a remote procedure call protocol encoded in JSON. It is a very simple protocol (and very similar to XML-RPC), defining only a handful of data types and commands. In contrast to XML-RPC or SOAP, it allows for bidirectional communication between the service and the client, treating each more like peers and allowing peers to call one another or send notifications to one another. It also allows multiple calls to be sent to a peer which may be answered out of order.


The server implementation should be able to respond to requests, and encapsulate all the below methods in a way that lets XML-RPC be implemented using the same framework (or possibly even Google's fast Protocol Buffers).

The implementation should also let the server be a send requests to the client too. Why? Because it'd be nice to have JSON clients be able to respond to add/remove signals if they want (obviously they have to connect to those signals first and indicate the callback).

There maybe more projects to investigate, but one C++ implementation of JSON-RPC exists at:



There are many methods that could be implemented, but initially, a minimum set to be functionally useful should be concentrated on.



Add an atom. Whether this is intepreted as a link or node depends on the atom arity (0 for a node), name (links have no name), and type (whether the given type inherits from node or link).

Returns the handle/UUID of the atom if successful and UNDEFINED_HANDLE if not.


Get an atom's detail by handle.


Remove an atom by handle.


Set the TruthValue of an atom by handle.

(Should support SimpleTruthValue, CountTruthValue, IndefiniteTruthValue, etc.)


Get the TruthValue of an atom by handle.


Get the AttentionValue of an atom by handle.


Set the AttentionValue of an atom by handle.


Return a list of types that the CogServer currently recognises.


Return a list of handles that are of a given Type..


load_module, unload_module

Attempt to load/unload a dynamic module.

(Should also create a list_modules command... which lists the modules that are loaded, and a available_modules command which lists the modules that were compiled... although the latter would probably require some CMake wizardry).


Return a list of available commands, these should be based on the Request objects registered with the CogServer (i.e the list will change depending on what modules are loaded), but also should include all of the above AtomSpace commands too.

If a string parameter is given, then only return commands that are prefixed with that string. This will be useful for eventually implementing a shell with command completion.


Return usage information for any of the commands, and also for the other JSON_RPC calls (so the AtomSpace ones will have to described manually, the CogServer commands have help info already).

agent control

As per those shown in the shell on start up...

  • agents-list: List running agents
  • agents-start: Start some agents
  • agents-start-loop: Start the agent loop
  • agents-step: Run a single cycle of an agent(s)
  • agents-stop: Stop some agents running
  • agents-stop-loop: Stop the agent loop


Possibly needs to considered separately to the other commands, but this should evaluate a string using the Scheme interpreter and return the result.


(should probably actually call this load_xml or something)

Similar to scm, but load raw XML.


Shutdown the server.