--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/network-api.md	Fri Dec 08 20:11:22 2017 +0100
@@ -0,0 +1,415 @@
+% networking API
+% David Demelier
+% 2017-12-08
+
+This guide will help you controlling irccd via sockets.
+
+Currently, irccd supports internet and unix sockets, you need at least one
+transport defined in your **irccd.conf**.
+
+# Syntax
+
+Irccd use JSON as protocol for sending and receiving data. A message must ends
+with `\r\n\r\n` to be complete, thus it's possible to write JSON messages in
+multiple lines.
+
+For example, this buffer will be parsed as two different messages.
+
+<div class="alert alert-success" role="alert">
+**Example**: two commands issued
+
+```json
+{
+  "param1": "value1"
+}
+
+{
+  "param1": "value1"
+}
+
+```
+</div>
+
+Warning: please note that the `\r\n\r\n` characters are the escape characters of
+         line feed and new line, not the concatenation of `\` and `r`.
+
+## Responses
+
+All commands emit a response with the following properties:
+
+  - **command**: (string) the result of the issued command,
+  - **error**: (int) the error error code, not defined on success.
+
+## Examples
+
+Success message.
+
+```json
+{
+  "command": "server-message",
+}
+```
+
+Command returned an error.
+
+```json
+{
+  "command": "server-message",
+  "status": "error",
+  "error": "4001"
+}
+```
+
+# List of all commands
+
+The following commands are available. Please note that a lot of commands require
+a server as the first argument, it’s one of defined in the **irccd.conf** file
+in the server section.
+
+## server-connect
+
+Connect to a server.
+
+## Properties
+
+  - **command**: (string) "server-connect",
+  - **name**: (string) the server unique id,
+  - **host**: (string) the host address,
+  - **port**: (int) the port number (Optional, default: 6667),
+  - **ssl**: (bool) use SSL (Optional, default: false),
+  - **sslVerify**: (bool) verify SSL (Optional, default: false),
+  - **nickname**: (string) the nickname to use (Optional, default: irccd),
+  - **username**: (string) the user name to use (Optional, default: irccd),
+  - **realname**: (string) the real name to use
+    (Optional, default: IRC Client Daemon),
+  - **ctcpVersion**: (string) the CTCP Version to answer
+    (Optional, default: the irccd's version),
+  - **commandChar**: (string) the command character to use to invoke commands
+    (Optional, default: !),
+  - **reconnectTries**: (int) the number of reconnection to try
+    (Optional, default: -1),
+  - **reconnectTimeout**: (int) the number of seconds to wait before retrying to
+    connect (Optional, default: 30).
+
+## Example
+
+```json
+{
+  "command": "server-connect",
+  "name": "myserver",
+  "host": "localhost",
+  "nickname": "edouard"
+}
+```
+
+## server-disconnect
+
+Disconnect from a server.
+
+If server is not specified, irccd disconnects all servers.
+
+## Properties
+
+  - **command**: (string) "server-disconnect",
+  - **server**: (string) the server unique id (Optional, default: none).
+
+## Example
+
+```json
+{
+  "command": "server-disconnect",
+  "server": "myserver"
+}
+```
+
+## server-info
+
+Get server information.
+
+## Properties
+
+  - **command**: (string) "server-info",
+  - **server**: (string) the server unique id.
+
+## Example
+
+```json
+{
+  "command": "server-info",
+  "server": "myserver"
+}
+```
+
+## Responses
+
+  - **name**: (string) the server unique id,
+  - **host**: (string) the server hostname,
+  - **port**: (int) the port,
+  - **ipv6**: (bool) true if using IPv6,
+  - **ssl**: (bool) true if connection is using SSL,
+  - **sslVerify**: (bool) true if SSL was verified,
+  - **channels**: (string list) list of channels.
+  - **nickname**: (string) the current nickname in use,
+  - **username**: (string) the username in use,
+  - **realname**: (string) the realname in use.
+
+## server-invite
+
+Invite the specified target on the channel.
+
+## Properties
+
+  - **command**: (string) "server-invite",
+  - **server**: (string) the server unique id,
+  - **target**: (string) the nickname to invite,
+  - **channel**: (string) the channel.
+
+## Example
+
+```json
+{
+  "command": "server-invite",
+  "server": "myserver",
+  "target": "edouard",
+  "channel": "#staff"
+}
+```
+
+## server-join
+
+Join the specified channel, the password is optional.
+
+## Properties
+
+  - **command**: (string) "server-join",
+  - **server**: (string) the server unique id,
+  - **channel**: (string) the channel to join,
+  - **password**: (string) the password (Optional, default: none).
+
+## Example
+
+```json
+{
+  "command": "server-join",
+  "server": "myserver",
+  "channel": "#games"
+}
+```
+
+## server-kick
+
+Kick the specified target from the channel, the reason is optional.
+
+## Properties
+
+  - **command**: (string) "server-kick",
+  - **server**: (string) the server unique id,
+  - **target**: (string) the target nickname,
+  - **channel**: (string) the channel,
+  - **reason**: (string) the reason (Optional, default: none).
+
+## Example
+
+```json
+{
+  "command": "server-kick",
+  "server": "myserver",
+  "target": "edouard",
+  "channel": "#staff",
+  "reason": "please be nice"
+}
+```
+
+## server-list
+
+Get the list of all connected servers.
+
+## Properties
+
+- **command**: (string) "server-list".
+
+## Example
+
+```json
+{
+  "command": "server-list"
+}
+```
+
+## Responses
+
+  - The following properties:
+    - **list**: (string list) the list of all server unique ids.
+
+## server-me
+
+Send an action emote.
+
+## Properties
+
+  - **command**: (string) "server-me",
+  - **server**: (string) the server unique id,
+  - **target**: (string) the target or channel,
+  - **message**: (string) the message.
+
+## Example
+
+```json
+{
+  "command": "server-me",
+  "server": "myserver",
+  "channel": "#staff",
+  "message": "like that"
+}
+```
+
+## server-message
+
+Send a message to the specified target or channel.
+
+## Properties
+
+  - **command**: (string) "server-message",
+  - **server**: (string) the server unique id,
+  - **target**: (string) the target or channel,
+  - **message**: (string) the message.
+
+## Example
+
+```json
+{
+  "command": "server-message",
+  "server": "myserver",
+  "target": "#staff",
+  "message": "this channel is nice"
+}
+```
+
+## server-mode
+
+Set the irccd's user mode.
+
+## Properties
+
+  - **command**: (string) "server-mode",
+  - **server**: (string) the server unique id,
+  - **mode**: (string) the mode.
+
+## Example
+
+```json
+{
+  "command": "server-mode",
+  "server": "myserver",
+  "mode": "mode"
+}
+```
+
+## server-nick
+
+Change irccd's nickname.
+
+## Properties
+
+  - **command**: (string) "server-nick",
+  - **server**: (string) the server unique id,
+  - **nickname**: (string) the new nickname.
+
+## Example
+
+```json
+{
+  "command": "server-nick",
+  "server": "myserver",
+  "nickname": "edouard"
+}
+```
+
+## server-notice
+
+Send a private notice to the specified target.
+
+## Properties
+
+  - **command**: (string) "server-notice",
+  - **server**: (string) the server unique id,
+  - **target**: (string) the target,
+  - **message**: (string) the notice message.
+
+## Example
+
+```json
+{
+  "command": "server-notice",
+  "server": "myserver",
+  "target": "edouard",
+  "message": "hello dude"
+}
+```
+
+## server-part
+
+Leave the specified channel, the reason is optional.
+
+Not all IRC servers support giving a reason to leave a channel, do not specify
+it if this is a concern.
+
+## Properties
+
+  - **command**: (string) "server-part",
+  - **server**: (string) the unique server id,
+  - **channel**: (string) the channel to leave,
+  - **reason**: (string) the reason (Optional, default: none).
+
+## Example
+
+```json
+{
+  "command": "server-part",
+  "server": "myserver",
+  "channel": "#staff",
+  "reason": "the reason"
+}
+```
+
+## server-reconnect
+
+Force reconnection of one or all servers.
+
+If server is not specified, all servers will try to reconnect.
+
+## Properties
+
+  - **command**: (string) "server-reconnect",
+  - **server**: (string) the server unique id (Optional, default: none).
+
+## Example
+
+```json
+{
+  "command": "server-reconnect",
+  "server": "myserver"
+}
+```
+
+## server-topic
+
+Change the topic of the specified channel.
+
+## Properties
+
+  - **command**: (string) "server-topic",
+  - **server**: (string) the unique server id,
+  - **channel**: (string) the channel,
+  - **topic**: (string) the new topic.
+
+## Example
+
+```json
+{
+  "command": "server-topic",
+  "server": "myserver",
+  "channel": "#staff",
+  "topic": "the new topic"
+}
+```