JSON RPC API

JSON-RPC 2.0

Dalek IRC Services ships with a JSON-RPC API. This follows the JSON-RPC 2.0 specification.

Interfacing

This, at the moment, is only done locally on port 1024, using POST method to send JSON requests (like in the below examples).

Calls must be made to the /api endpoint.

Examples:

Example one: Getting information

An example call to get the MD for user Valware:

curl -s --insecure -X POST -d '{"jsonrpc": "2.0", "method": "md.get", "params": {"user": "Valware"}, "id": 123}' http://localhost:1024/api

which returns something like:

{
    "jsonrpc": "2.0",
    "result": {
        "operclass": "netadmin",
        "operlogin": "Valware",
        "creationtime": "1661022098",
        "certfp": "8e8fb90324550d3a379c75c50e9e3cd52e1e21723532eaa4b85b61dc84f48e7e",
        "tls_cipher": "TLSv1.3-TLS_CHACHA20_POLY1305_SHA256",
        "geoip": "cc=FR|cd=France"
    },
    "id": 123
}

Example two: Executing remote procedures

An example of how to forcefully login a user who is on IRC

curl -s --insecure -X POST -d '{"jsonrpc": "2.0", "method": "operserv.forcelogin", "params": {"user": "Valware", "account": "Valware"}, "id": 123}' http://localhost:1024/api

will return something like:

{
    "jsonrpc": "2.0",
    "result": "User \"Valware\" logged into account \"Valware\" successfully.",
    "id": 123
}

Notes

• Your RPC request must contain "jsonrpc": "2.0", otherwise it will not be valid.
• You must specify an id. This can be random, however the reply will reflect the ID so you can be sure the response is for what you requested.
• The method must be a valid Dalek RPC method as documented below or added by a third-party module.
• The result field in the response JSON object will contain the result of your request.

Built-In RPC method names and their parameters

The list below shows methods currently implemented. Things are still being implemented, so hold tight.

Name	Params	Param Description	Return
module.load	module	The directory and name of the module, e.g; third/os_raw (the same as the loadmodule() command in modules.conf)	result on success, error on failure.
module.unload	module	The name of the module, e.g; os_raw to unload.
module.list	None	None	result containing a list of modules and their information.
chg.host	user, host	user must be the nick or UID of a valid user on IRC. host must be a valid hostmask	result on success, error on failure.
chg.ident	user, ident	user must be the nick or UID of a valid user on IRC. ident must be a valid ident	result on success, error on failure.
chg.name	user, name	user must be the nick or UID of a valid user on IRC. name must be a valid Real Name/GECOS	result on success, error on failure.
md.get	user	user must be the nick or UID of a valid user on IRC	result containing a list of MD
operserv.forcelogin	user, account	user must be the nick or UID of a valid user on IRC. account must be a valid WordPress account linked to your IRC.	result on success, error on failure.
user.get	nick	user must be the nick or UID of a valid user on IRC.`	result on success, error on failure.
user.list	None	None	result containing a list of nicks and relative information
channel.get	channel	channel must be a valid channel that exists on IRC.	result on success, error on failure
channel.list	None	None	result containing a list of channels and relative information.
rehash	server	server must be the name or SID of a server	error containing information about what went wrong, or result with "Success"

Error codes

You may receive error codes. This is a documented table of error codes and their meanings.

Code	Message	Description
-32700	Parse error	Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600	Invalid request	The JSON sent is not a valid Request object
-32601	Method not found	The method does not exist/is not available
-32602	Invalid parameters	The method parameters you specified are invalid
-32603	Internal error	There was an error processing your request
-32000	Permission denied	You do not have permission to make that request
-1000	Not found	Nick or channel was not found
-1001	Already exists	Resource already exists by that name (e.g; on nick-change request, a g-line, etc)
-1002	Invalid name	Not a valid name, e.g; channel name, nick name.
-1003	User not in channel	The specified user/nick is not in the specified channel
-1004	Too many entries	There are too many entries in the resource, e.g; ban list
-1005	Resource denied	Permission denied for user, unrelated to RPC permissions.