JSON-RPC:Technical documentation

This is the technical documentation for JSON-RPC for developers and people who want to interact with UnrealIRCd via the JSON-RPC API. It assumes you have read and configured your UnrealIRCd according to the JSON-RPC article.

Below we explain the transports that are available (domain sockets, HTTPS POST and websockets), the JSON-RPC protocol and finally all the methods / API calls that are available.

UNIX domain socket
This is for local connections only. On the server side you have this: listen { file "/home/xyz/unrealircd/data/rpc.socket"; options { rpc; } } NOTE: UnrealIRCd 6.0.6 and later (and current git) will have this listen block by default, via rpc.modules.default.conf.

Then simply connect to the socket and you can issue JSON-RPC requests directly. Example: $ nc -U ~/unrealircd/data/rpc.sock {"jsonrpc": "2.0", "method": "channel.list", "params": {}, "id": 123} {"jsonrpc": "2.0", "method": "channel.list", "id": 123, "response": {"list": []}}

There is no authentication being done, as only local users can use this and the socket is only readable/writable by the user running UnrealIRCd by default (rwx--).

You can issue multiple requests (even in parallel, no need to wait for the response). The connection is not closed. The connection is only closed if some fatal JSON parsing error is encountered such as a missing. Normally that should never happen. Other errors such as an unknown method being called, invalid parameter count, etc. are not fatal.

HTTPS POST
On the server side this requires you to open up a port (Listen block) and add at least one api user (Rpc-user block): listen { ip *; port 8000; options { rpc; } }

rpc-user apiuser { match { ip 192.168.*; } password "password"; }

Then do a  request to   with the JSON request. You must do this over.

Example: curl -s --insecure -X POST -d '{"jsonrpc": "2.0", "method": "channel.list", "params": {}, "id": 123}' https://apiuser:password@127.0.0.1:8000/api The connection is closed after processing the request. If you want to issue another API call then do a new HTTPS POST. If you want streaming requests/responses, use HTTPS Websocket (see next section).

HTTPS Websocket
On the server side the config is the same as for HTTPS POST. You open up a port (Listen block) and add at least one api user (Rpc-user block): listen { ip *; port 8000; options { rpc; } }

rpc-user apiuser { match { ip 192.168.*; } password "password"; }

Make a HTTPS websocket connection (not HTTP!) and then you can send JSON requests. Eg: {"jsonrpc": "2.0", "method": "channel.list", "params": {}, "id": 123} The connection is kept open so you can issue more JSON-RPC requests. You may also send multiple requests in parallel, you don't have to wait for a response. The connection is only closed upon:
 * A fatal error, such as a JSON parsing error. Obviously this should never happen.
 * When the client does not respond to a websocket PING in time (as required by the websocket specification). Note that browsers automatically PONG back upon PING, so you don't have to worry about it there.

JSON-RPC Methods
The following methods are currently implemented in the git version (with links to documentation!):
 * rpc:
 * stats:
 * user:,  ,  ,  ,  ,  ,  ,  ,
 * server:,  ,  ,  ,
 * channel:,  ,  ,  ,
 * server_ban:,  ,  ,
 * server_ban_exception:,  ,  ,
 * spamfilter:,  ,  ,
 * name_ban:,  ,  ,

All the documentation for this is also viewable via the JSON-RPC Methods category