1. Introduction

This document is the specification of api relay protocol: the protocol used to relay WeeChat data to clients using an HTTP REST API.

1.1. Terminology

The following terms are used in this document:

  • relay: this is the WeeChat with relay plugin, which acts as "server" and allows clients to connect

  • client: this is a software connected to relay via a network connection (WeeChat itself or a remote interface).

1.2. Network diagram

The clients are connected to relay like shown in this diagram:

                                              ┌──────────┐ Workstation
 ┌────────┐                               ┌───┤ client 1 │ (Linux, Windows,
 │  irc   │◄──┐  ╔═══════════╤═══════╗    │   └──────────┘ BSD, macOS, …)
 └────────┘   └──╢           │       ║◄───┘   ┌──────────┐
   ......        ║  WeeChat  │ Relay ║◄───────┤ client 2 │ Mobile device
 ┌────────┐   ┌──╢           │       ║◄───┐   └──────────┘ (Android, iPhone, …)
 │ jabber │◄──┘  ╚═══════════╧═══════╝    │      ......
 └────────┘                               │   ┌──────────┐
   ......                                 └───┤ client N │ Other devices
                                              └──────────┘


└────────────┘   └───────────────────┘╘══════╛└────────────────────────────────┘
network servers    ncurses interface    relay         remote interfaces

All clients here are clients using api protocol in relay plugin.
The relay plugin also allows irc and weechat protocols (not described in this document).

2. Protocol generalities

  • Connections from client to relay are made using TCP sockets on IP/port used by relay plugin to listen to new connections.

  • Number of clients is limited by the option relay.network.max_clients.

  • Each client is independent from other clients.

  • The api relay is an HTTP REST API using JSON format for input/output.

  • Messages are automatically compressed (deflate, gzip, zstd and permessage-deflate for websocket protocol).

  • WeeChat can be used as client of this relay.

2.1. API versioning

The API is versioned using a "practical" semantic Versioning ↗, like WeeChat, on three digits X.Y.Z, where:

  • X is the major version

  • Y is the minor version

  • Z is the patch version.

Example: version 2.0.0 brings breaking changes vs version 1.2.3.

The API version is returned by the version resource.

2.2. API schema

You can browse and test the API online: WeeChat Relay API ↗.

2.3. Response codes

The following HTTP response codes can be sent back to the client:

  • 200 OK: response OK with a body (JSON)

  • 204 No Content: response OK without body

  • 400 Bad Request: invalid request received

  • 401 Unauthorized: missing or invalid credentials

  • 403 Forbidden: insufficient permissions

  • 404 Not Found: resource not found

  • 500 Internal Server Error: internal server error

  • 503 Service Unavailable: service unavailable

When connected via websocket protocol, an extra response code is sent when WeeChat pushes data to the client on events:

  • 0 Event: event pushed to the client, if synchronization is enabled with sync resource.

2.4. Date format

The date format is ISO 8601 ↗, using UTC timezone (this is then different from the display by WeeChat which uses the local timezone).
The dates are returned with maximum precision: up to microseconds if possible, or milliseconds, or just seconds.

Examples:

2023-12-05T19:46:03.847625Z
2023-12-05T19:46:03.847Z
2023-12-05T19:46:03Z

3. Authentication

The password must be sent in the header Authorization with Basic authentication schema or in the header Sec-WebSocket-Protocol (see details below).

The password can be sent as plain text or hashed, with one of these formats for user and password:

  • plain:<password>

  • hash:sha256:<timestamp>:<hash>

  • hash:sha512:<timestamp>:<hash>

  • hash:pbkdf2+sha256:<timestamp>:<iterations>:<hash>

  • hash:pbkdf2+sha512:<timestamp>:<iterations>:<hash>

Where:

  • <password> is the password as plain text

  • <timestamp> is the current timestamp as integer (number of seconds since the Unix Epoch); it is used to prevent replay attacks

  • <iterations> is the number of iterations (for PBKDF2 algorithm only)

  • <hash> is the hashed value of timestamp + password (as hexadecimal)

Note
 The max number of seconds allowed before and after the received time (when password is sent hashed) can be configured with option relay.network.time_window.

Example:

  • current timestamp is 1706431066

  • password is secret_password

  • hash algorithm is sha256

  • result hash is the SHA256 of string 1706431066secret_password which is as hexadecimal: dfa1db3f6bb6445d18d9ec7427c10f6421274e3a4751e6c1ffc7dd28c94eadf6

  • the Authorization header is the base64 encoded string hash:sha256:1706431066:dfa1db3f6bb6445d18d9ec7427c10f6421274e3a4751e6c1ffc7dd28c94eadf6: aGFzaDpzaGEyNTY6MTcwNjQzMTA2NjpkZmExZGIzZjZiYjY0NDVkMThkOWVjNzQyN2MxMGY2NDIxMjc0ZTNhNDc1MWU2YzFmZmM3ZGQyOGM5NGVhZGY2.

The headers Authorization and Sec-WebSocket-Protocol are allowed in the first request with the websocket protocol or any HTTP request in the other cases.

Request example with plain text password:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/version'

Request example with hashed password (SHA256):

curl -L -u 'hash:sha256:1706431066:dfa1db3f6bb6445d18d9ec7427c10f6421274e3a4751e6c1ffc7dd28c94eadf6' 'https://localhost:9000/api/version'

If TOTP (Time-based One-Time Password) is enabled on WeeChat/relay side (option relay.network.totp_secret is set), you must send the TOTP value in the x-weechat-totp header like this:

curl -L -u 'hash:sha256:1706431066:dfa1db3f6bb6445d18d9ec7427c10f6421274e3a4751e6c1ffc7dd28c94eadf6' -H "x-weechat-totp: 123456" 'https://localhost:9000/api/version'

In case of error, a response 401 Unauthorized is returned with a field error in JSON data that describes the error.

Response: missing password:

HTTP/1.1 401 Unauthorized
{
    "error": "Missing password"
}

Response: wrong password:

HTTP/1.1 401 Unauthorized
{
    "error": "Invalid password"
}

Response: invalid hash algorithm:

HTTP/1.1 401 Unauthorized
{
    "error": "Invalid hash algorithm (not found or not supported)"
}

Response: invalid timestamp:

HTTP/1.1 401 Unauthorized
{
    "error": "Invalid timestamp"
}

Response: invalid number of iterations:

HTTP/1.1 401 Unauthorized
{
    "error": "Invalid number of iterations"
}

Response: missing TOTP:

HTTP/1.1 401 Unauthorized
{
    "error": "Missing TOTP"
}

Response: wrong TOTP:

HTTP/1.1 401 Unauthorized
{
    "error": "Invalid TOTP"
}

3.1. Sec-WebSocket-Protocol

The JavaScript WebSocket API used in current web browsers does not support specifying the Authorization header. Therefore it’s also supported to send the password in the Sec-WebSocket-Protocol header which is the only header possible to set with this API.

To use this header, you must specify the sub-protocols api.weechat and base64url.bearer.authorization.weechat.<auth> where <auth> is the base64url encoded string of the password in the same format as explained above.

Example with password secret_password encoded in plain text. This makes the string to base64url encode plain:secret_password which is cGxhaW46c2VjcmV0X3Bhc3N3b3Jk.

Sec-WebSocket-Protocol: api.weechat, base64url.bearer.authorization.weechat.cGxhaW46c2VjcmV0X3Bhc3N3b3Jk

This can be set with the JavaScript WebSocket API like this:

const ws = new WebSocket("wss://localhost:9000/api", [
  "api.weechat",
  "base64url.bearer.authorization.weechat.cGxhaW46c2VjcmV0X3Bhc3N3b3Jk",
])

4. Compression

Compression of response body is automatic and based on header Accept-Encoding sent by the client.

Supported compression formats are:

  • deflate (zlib)

  • gzip

  • zstd

Request example:

curl -L -u 'plain:secret_password' -H "Accept-Encoding: gzip" 'https://localhost:9000/api/version'

Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Encoding: gzip
Content-Length: 77
[77 bytes data]

Note: with websocket protocol, the extension "permessage-deflate" allows to compress messages with zlib.

5. Resources

5.1. Preflight request

The preflight request with HTTP method OPTIONS is used by web browsers to check that the server (WeeChat) will permit the actual request.

Request example: check that request GET /api/version is authorized:

OPTIONS /api/version HTTP/1.1
Host: localhost:9000
Connection: keep-alive
Accept: */*
Access-Control-Request-Method: GET
Access-Control-Request-Headers: authorization
Origin: https://localhost
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36
Sec-Fetch-Mode: cors
Sec-Fetch-Site: same-site
Sec-Fetch-Dest: empty
Referer: https://localhost/
Accept-Encoding: gzip, deflate, br, zstd
Accept-Language: en-US,en;q=0.9,fr;q=0.8

Response:

HTTP/1.1 204 No Content
Access-Control-Allow-Methods: GET, POST, PUT, DELETE
Access-Control-Allow-Headers: origin, content-type, accept, authorization
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 0

5.2. Handshake

Perform an handshake between the client and WeeChat.

This resource is accessible without authentication.

Endpoint:

POST /api/handshake

Body parameters:

  • password_hash_algo (array of strings, optional): list of hash algorithms supported by the client, each string can be:

    • plain: plain-text password (no hash)

    • sha256: hash SHA256

    • sha512: hash SHA512

    • pbkdf2+sha256: hash PBKDF2 with SHA256

    • pbkdf2+sha512: hash PBKDF2 with SHA512

The response has the following fields:

  • password_hash_algo (string): the hash algorithm to use (null if no algorithm is compatible)

  • password_hash_iterations (integer): the number of iterations to use if hash PBKDF2 is used

  • totp (boolean): true if TOTP is enabled in WeeChat (then the client must send TOTP in specific header), false otherwise

Request example:

curl -L -X POST -d '{"password_hash_algo": ["plain", "sha256", "sha512"]}' 'https://localhost:9000/api/handshake'

Response:

HTTP/1.1 200 OK
{
    "password_hash_algo": "sha512",
    "password_hash_iterations": 100000,
    "totp": false
}

5.3. Version

Return the WeeChat and relay API versions.

Endpoint:

GET /api/version

Request example:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/version'

Response:

HTTP/1.1 200 OK
{
    "weechat_version": "4.2.0-dev",
    "weechat_version_git": "v4.1.0-143-g0b1cda1c4",
    "weechat_version_number": 67239936,
    "relay_api_version": "0.0.1",
    "relay_api_version_number": 1
}

5.4. Buffers

Return buffers, lines and nicks.

Endpoints:

GET /api/buffers
GET /api/buffers/{buffer_id}
GET /api/buffers/{buffer_name}

Path parameters:

  • buffer_id (integer, optional): buffer unique identifier (not to be confused with the buffer number, which is different)

  • buffer_name (string, optional): buffer name

Query parameters:

  • lines (integer, optional, default: 0): number of lines to return in buffers with formatted content:

    • negative number: return N lines from the end of buffer (newest lines)

    • 0: do not return any line

    • positive number: return N lines from the beginning of buffer (oldest lines)

  • lines_free (integer, optional, default: 0 if lines is 0, otherwise all lines): number of lines to return in buffers with free content:

    • negative number: return N lines from the end of buffer

    • 0: do not return any line

    • positive number: return N lines from the beginning of buffer

  • nicks (boolean, optional, default: false): return nicks in buffer

  • colors (string, optional, default: ansi): how to return strings with color codes:

    • ansi: return ANSI color codes

    • weechat: return WeeChat internal color codes

    • strip: strip colors

Request example: get all buffers without lines:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/buffers'

Response:

HTTP/1.1 200 OK
[
    {
        "id": 1709932823238637,
        "name": "core.weechat",
        "short_name": "weechat",
        "number": 1,
        "type": "formatted",
        "hidden": false,
        "title": "WeeChat 4.2.0-dev (C) 2003-2023 - https://weechat.org/",
        "modes": "",
        "input_prompt": "",
        "input": "",
        "input_position": 0,
        "input_multiline": false,
        "nicklist": false,
        "nicklist_case_sensitive": false,
        "nicklist_display_groups": true,
        "time_displayed": true,
        "local_variables": {
            "plugin": "core",
            "name": "weechat"
        },
        "keys": []
    },
    {
        "id": 1709932823423765,
        "name": "irc.server.libera",
        "short_name": "libera",
        "number": 2,
        "type": "formatted",
        "hidden": false,
        "title": "IRC: irc.libera.chat/6697 (2001:4b7a:a008::6667)",
        "modes": "",
        "input_prompt": "",
        "input": "",
        "input_position": 0,
        "input_multiline": false,
        "nicklist": false,
        "nicklist_case_sensitive": false,
        "nicklist_display_groups": true,
        "time_displayed": true,
        "local_variables": {
            "plugin": "irc",
            "name": "server.libera",
            "type": "server",
            "server": "libera",
            "channel": "libera",
            "charset_modifier": "irc.libera",
            "nick": "alice",
            "tls_version": "TLS1.3",
            "host": "~alice@example.com"
        },
        "keys": []
    },
    {
        "id": 1709932823649069,
        "name": "irc.libera.#weechat",
        "short_name": "#weechat",
        "number": 3,
        "type": "formatted",
        "hidden": false,
        "title": "Welcome to the WeeChat official support channel",
        "modes": "+nt",
        "input_prompt": "\u001b[92m@\u001b[96malice\u001b[48;5;22m(\u001b[39mi\u001b[48;5;22m)",
        "input": "",
        "input_position": 0,
        "input_multiline": false,
        "nicklist": true,
        "nicklist_case_sensitive": false,
        "nicklist_display_groups": false,
        "time_displayed": true,
        "local_variables": {
            "plugin": "irc",
            "name": "libera.#weechat",
            "type": "channel",
            "server": "libera",
            "channel": "#weechat",
            "nick": "alice",
            "host": "~alice@example.com"
        },
        "keys": []
    }
]

Request example: get WeeChat core buffer with only last line and no color codes:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/buffers/core.weechat?lines=-1&colors=strip'

Response:

HTTP/1.1 200 OK
{
    "id": 1709932823238637,
    "name": "core.weechat",
    "short_name": "weechat",
    "number": 1,
    "type": "formatted",
    "hidden": false,
    "title": "WeeChat 4.2.0-dev (C) 2003-2023 - https://weechat.org/",
    "modes": "",
    "input_prompt": "",
    "input": "",
    "input_position": 0,
    "input_multiline": false,
    "nicklist": false,
    "nicklist_case_sensitive": false,
    "nicklist_display_groups": true,
    "time_displayed": true,
    "local_variables": {
        "plugin": "core",
        "name": "weechat"
    },
    "keys": [],
    "lines": [
        {
            "id": 10,
            "y": -1,
            "date": "2023-12-24T08:17:20.786538Z",
            "date_printed": "2023-12-24T08:17:20.786538Z",
            "displayed": true,
            "highlight": false,
            "notify_level": 0,
            "prefix": "",
            "message": "Plugins loaded: alias, buflist, charset, exec, fifo, fset, guile, irc, javascript, logger, lua, perl, php, python, relay, ruby, script, spell, tcl, trigger, typing, xfer",
            "tags": []
        }
    ]
}

Request example: get an IRC channel buffers with nicks:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/buffers/irc.libera.%23weechat?nicks=true'

Response:

HTTP/1.1 200 OK
{
    "id": 1709932823649069,
    "name": "irc.libera.#weechat",
    "short_name": "#weechat",
    "number": 3,
    "type": "formatted",
    "hidden": false,
    "title": "Welcome to the WeeChat official support channel",
    "modes": "+nt",
    "input_prompt": "\u001b[92m@\u001b[96malice\u001b[48;5;22m(\u001b[39mi\u001b[48;5;22m)",
    "input": "",
    "input_position": 0,
    "input_multiline": false,
    "nicklist": true,
    "nicklist_case_sensitive": false,
    "nicklist_display_groups": false,
    "time_displayed": true,
    "local_variables": {
        "plugin": "irc",
        "name": "libera.#weechat",
        "type": "channel",
        "server": "libera",
        "channel": "#weechat",
        "nick": "alice",
        "host": "~alice@example.com"
    },
    "keys": [],
    "nicklist_root": {
        "id": 0,
        "parent_group_id": -1,
        "name": "root",
        "color_name": "",
        "color": "",
        "visible": false,
        "groups": [
            {
                "id": 1709932823649181,
                "parent_group_id": 0,
                "name": "000|o",
                "color_name": "weechat.color.nicklist_group",
                "color": "\u001b[32m",
                "visible": true,
                "groups": [],
                "nicks": [
                    {
                        "id": 1709932823649184,
                        "parent_group_id": 1709932823649181,
                        "prefix": "@",
                        "prefix_color_name": "lightgreen",
                        "prefix_color": "\u001b[92m",
                        "name": "alice",
                        "color_name": "bar_fg",
                        "color": "",
                        "visible": true
                    }
                ]
            },
            {
                "id": 1709932823649189,
                "parent_group_id": 0,
                "name": "001|h",
                "color_name": "weechat.color.nicklist_group",
                "color": "\u001b[32m",
                "visible": true,
                "groups": [],
                "nicks": []
            },
            {
                "id": 1709932823649203,
                "parent_group_id": 0,
                "name": "002|v",
                "color_name": "weechat.color.nicklist_group",
                "color": "\u001b[32m",
                "visible": true,
                "groups": [],
                "nicks": []
            },
            {
                "id": 1709932823649210,
                "parent_group_id": 0,
                "name": "999|...",
                "color_name": "weechat.color.nicklist_group",
                "color": "\u001b[32m",
                "visible": true,
                "groups": [],
                "nicks": []
            }
        ],
        "nicks": []
    }
}

Request example: get fset buffer:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/buffers/fset.fset'

Response:

HTTP/1.1 200 OK
{
    "id": 1709932823897200,
    "name": "fset.fset",
    "short_name": "",
    "number": 4,
    "type": "free",
    "hidden": false,
    "title": "\u001b[96m1/\u001b[36m3565 | Filter: \u001b[93m* | Sort: \u001b[97m~name | Key(input): alt+space=toggle boolean, alt+'-'(-)=subtract 1 or set, alt+'+'(+)=add 1 or append, alt+f,alt+r(r)=reset, alt+f,alt+u(u)=unset, alt+enter(s)=set, alt+f,alt+n(n)=set new value, alt+f,alt+a(a)=append, alt+','=mark/unmark, shift+down=mark and move down, shift+up=move up and mark, ($)=refresh, ($$)=unmark/refresh, (m)=mark matching options, (u)=unmark matching options, alt+p(p)=toggle plugins desc, alt+v(v)=toggle help bar, ctrl+x(x)=switch format, (q)=close buffer",
    "modes": "",
    "input_prompt": "",
    "input": "",
    "input_position": 0,
    "input_multiline": false,
    "nicklist": false,
    "nicklist_case_sensitive": false,
    "nicklist_display_groups": true,
    "time_displayed": true,
    "local_variables": {
        "plugin": "fset",
        "name": "fset",
        "type": "option",
        "filter": "*"
    },
    "keys": [
        {
            "key": "ctrl-l",
            "command": "/fset -refresh"
        },
        {
            "key": "ctrl-n",
            "command": "/eval ${if:${weechat.bar.buflist.hidden}?/fset -down:/buffer +1}"
        },
        {
            "key": "ctrl-x",
            "command": "/fset -format"
        },
        {
            "key": "down",
            "command": "/fset -down"
        },
        {
            "key": "f11",
            "command": "/fset -left"
        },
        {
            "key": "f12",
            "command": "/fset -right"
        },
        {
            "key": "meta-+",
            "command": "/fset -add 1"
        },
        {
            "key": "meta--",
            "command": "/fset -add -1"
        },
        {
            "key": "meta-comma",
            "command": "/fset -mark"
        },
        {
            "key": "meta-end",
            "command": "/fset -go end"
        },
        {
            "key": "meta-f,meta-a",
            "command": "/fset -append"
        },
        {
            "key": "meta-f,meta-n",
            "command": "/fset -setnew"
        },
        {
            "key": "meta-f,meta-r",
            "command": "/fset -reset"
        },
        {
            "key": "meta-f,meta-u",
            "command": "/fset -unset"
        },
        {
            "key": "meta-home",
            "command": "/fset -go 0"
        },
        {
            "key": "meta-p",
            "command": "/mute /set fset.look.show_plugins_desc toggle"
        },
        {
            "key": "meta-q",
            "command": "/input insert meta-q fset ${property}"
        },
        {
            "key": "meta-return",
            "command": "/fset -set"
        },
        {
            "key": "meta-space",
            "command": "/fset -toggle"
        },
        {
            "key": "meta-v",
            "command": "/bar toggle fset"
        },
        {
            "key": "shift-down",
            "command": "/fset -mark; /fset -down"
        },
        {
            "key": "shift-up",
            "command": "/fset -up; /fset -mark"
        },
        {
            "key": "up",
            "command": "/fset -up"
        }
    ]
}

Lines

Return lines in a buffer.

Endpoints:

GET /api/buffers/{buffer_id}/lines
GET /api/buffers/{buffer_id}/lines/{line_id}
GET /api/buffers/{buffer_name}/lines
GET /api/buffers/{buffer_name}/lines/{line_id}

Path parameters:

  • buffer_id (integer, required): buffer unique identifier (not to be confused with the buffer number, which is different)

  • buffer_name (string, required): buffer name

  • line_id (integer, optional): return a single line with this identifier

Query parameters:

  • lines (integer, optional, default: all lines): number of lines to return:

    • negative number: return N lines from the end of buffer (newest lines)

    • 0: do not return any line (allowed but doesn’t make sense with this resource)

    • positive number: return N lines from the beginning of buffer (oldest lines)

  • colors (string, optional, default: ansi): how to return strings with color codes:

    • ansi: return ANSI color codes

    • weechat: return WeeChat internal color codes

    • strip: strip colors

Request example: get last 1000 lines of a buffer, without color codes:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/buffers/irc.libera.%23weechat/lines?lines=-1000&colors=strip'

Response:

HTTP/1.1 200 OK
[
    {
        "id": 0,
        "y": -1,
        "date": "2023-12-05T19:46:03.847625Z",
        "date_printed": "2023-12-05T19:46:03.847625Z",
        "displayed": true,
        "highlight": false,
        "notify_level": 0,
        "prefix": "-->",
        "message": "alice (~alice@example.com) has joined #test",
        "tags": [
            "irc_join",
            "irc_tag_account=alice",
            "irc_tag_time=2023-12-05T19:46:03.847Z",
            "nick_alice",
            "host_~alice@example.com",
            "log4"
        ]
    },
    {
        "id": 1,
        "y": -1,
        "date": "2023-12-05T19:46:03.986543Z",
        "date_printed": "2023-12-05T19:46:03.986543Z",
        "displayed": true,
        "highlight": false,
        "notify_level": 0,
        "prefix": "--",
        "message": "Mode #test [+Cnst] by zirconium.libera.chat",
        "tags": [
            "irc_mode",
            "irc_tag_time=2023-12-05T19:46:03.986Z",
            "nick_zirconium.libera.chat",
            "log3"
        ]
    },
    {
        "id": 2,
        "y": -1,
        "date": "2023-12-05T19:46:04.287546Z",
        "date_printed": "2023-12-05T19:46:04.287546Z",
        "displayed": true,
        "highlight": false,
        "notify_level": 0,
        "prefix": "--",
        "message": "Channel #test: 1 nick (1 op, 0 voiced, 0 regular)",
        "tags": [
            "irc_366",
            "irc_numeric",
            "irc_tag_time=2023-12-05T19:46:04.287Z",
            "nick_zirconium.libera.chat",
            "log3"
        ]
    }
]

Nicks

Return nicks in a buffer.

Endpoints:

GET /api/buffers/{buffer_id}/nicks
GET /api/buffers/{buffer_name}/nicks

Path parameters:

  • buffer_id (integer, required): buffer unique identifier (not to be confused with the buffer number, which is different)

  • buffer_name (string, required): buffer name

Request example: get nicks of a buffer:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/buffers/irc.libera.%23weechat/nicks'

Response:

HTTP/1.1 200 OK
{
    "id": 0,
    "parent_group_id": -1,
    "name": "root",
    "color_name": "",
    "color": "",
    "visible": false,
    "groups": [
        {
            "id": 1709932823649181,
            "parent_group_id": 0,
            "name": "000|o",
            "color_name": "weechat.color.nicklist_group",
            "color": "\u001b[32m",
            "visible": true,
            "groups": [],
            "nicks": [
                {
                    "id": 1709932823649184,
                    "parent_group_id": 1709932823649181,
                    "prefix": "@",
                    "prefix_color_name": "lightgreen",
                    "prefix_color": "\u001b[92m",
                    "name": "alice",
                    "color_name": "bar_fg",
                    "color": "",
                    "visible": true
                }
            ]
        },
        {
            "id": 1709932823649189,
            "parent_group_id": 0,
            "name": "001|h",
            "color_name": "weechat.color.nicklist_group",
            "color": "\u001b[32m",
            "visible": true,
            "groups": [],
            "nicks": []
        },
        {
            "id": 1709932823649203,
            "parent_group_id": 0,
            "name": "002|v",
            "color_name": "weechat.color.nicklist_group",
            "color": "\u001b[32m",
            "visible": true,
            "groups": [],
            "nicks": []
        },
        {
            "id": 1709932823649210,
            "parent_group_id": 0,
            "name": "999|...",
            "color_name": "weechat.color.nicklist_group",
            "color": "\u001b[32m",
            "visible": true,
            "groups": [],
            "nicks": []
        }
    ],
    "nicks": []
}

5.5. Hotlist

Return hotlist.

Endpoint:

GET /api/hotlist

Request example:

curl -L -u 'plain:secret_password' 'https://localhost:9000/api/hotlist'

Response:

HTTP/1.1 200 OK
[
    {
        "priority": 0,
        "date": "2024-03-17T16:38:51.572834Z",
        "buffer_id": 1710693531508204,
        "count": [
            44,
            0,
            0,
            0
        ]
    },
    {
        "priority": 0,
        "date": "2024-03-17T16:38:51.573028Z",
        "buffer_id": 1710693530395959,
        "count": [
            14,
            0,
            0,
            0
        ]
    },
    {
        "priority": 0,
        "date": "2024-03-17T16:38:51.611617Z",
        "buffer_id": 1710693531529248,
        "count": [
            4,
            0,
            0,
            0
        ]
    }
]

5.6. Input

Send command or text to a buffer.

Endpoint:

POST /api/input

Body parameters:

  • buffer_id (integer, optional): buffer unique identifier (not to be confused with the buffer number, which is different)

  • buffer (string, optional, default: core.weechat): buffer name

  • command (string, required): command or text to send to the buffer

Request example: say "hello!" on channel #weechat:

curl -L -u 'plain:secret_password' -X POST \
  -d '{"buffer": "irc.libera.#weechat", "command": "hello!"}' \
  'https://localhost:9000/api/input'

Response:

HTTP/1.1 204 No content

Request example: part and close channel #weechat (command executed on WeeChat core buffer):

curl -L -u 'plain:secret_password' -X POST \
  -d '{"command": "/buffer close irc.libera.#weechat"}' \
  'https://localhost:9000/api/input'

Response:

HTTP/1.1 204 No content

5.7. Ping

Send a "ping" request.

Endpoint:

POST /api/ping

Body parameters:

  • data (string, optional): string that is sent back in the response

Request example: no body:

curl -L -u 'plain:secret_password' -X POST 'https://localhost:9000/api/ping'

Response:

HTTP/1.1 204 No content

Request example: with data:

curl -L -u 'plain:secret_password' -X POST \
  -d '{"data": "1702835741"}' \
  'https://localhost:9000/api/ping'

Response:

HTTP/1.1 200 OK
{
    "data": "1702835741"
}

5.8. Sync

Start or stop synchronization of data with WeeChat.

This resource can be used only when the client is connected with websocket protocol, as WeeChat will push messages to the client at any time.

If this resource is used without a websocket connection, an error 403 (Forbidden) is returned.

Endpoint:

POST /api/sync

Body parameters:

  • sync (boolean, optional, default: true): true to enable synchronization with WeeChat

  • nicks (boolean, optional, default: true): true to receive nick updates in buffers (used only if sync is true)

  • input (boolean, optional, default: true): true to synchronize buffer input from remote relay to local client (used only if sync is true)

  • colors (string, optional, default: ansi): how to return strings with color codes (used only if sync is true):

    • ansi: return ANSI color codes

    • weechat: return WeeChat internal color codes

    • strip: strip colors

Request example with websocket protocol:

{
    "request": "POST /api/sync",
    "body": {
        "nicks": false
    }
}

Response:

{
    "code": 204,
    "message": "No Content",
    "request": "POST /api/sync",
    "request_body": {
        "nicks":false
    },
    "body_type": null,
    "body": null
}

Request example without websocket protocol (not authorized):

curl -L -u 'plain:secret_password' -X POST \
  -d '{"nicks": false}' \
  'https://localhost:9000/api/sync'

Response:

HTTP/1.1 403 Forbidden
{
    "error": "Sync resource is available only with a websocket connection"
}

6. Websocket

Websocket protocol is used to make a persistent connection between the client and WeeChat and receive events in real-time if synchronization is enabled with sync resource.

Authentication must be done only one time when the websocket protocol is used (see authentication).

6.1. Websocket handshake

To establish the connection, a handshake is performed on the /api endpoint and looks like:

GET /api HTTP/1.1
Host: localhost:9000
Connection: Upgrade
Pragma: no-cache
Cache-Control: no-cache
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
Upgrade: websocket
Origin: https://example.com
Sec-WebSocket-Version: 13
Accept-Encoding: gzip, deflate, br
Accept-Language: en-US,en;q=0.9,fr;q=0.8
Sec-WebSocket-Key: 2XE8VAJktqi3Tpw5QnfxVQ==
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits

WeeChat returns its handshake response to confirm that websocket protocol is properly supported (and authentication was successful):

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: PaY9vRflWeOKuD0/F7e5gD9At9U=
Sec-WebSocket-Extensions: permessage-deflate; client_max_window_bits
Note
 The Sec-WebSocket-Accept value returned is the SHA-1 hash of the value received, concatenated to the GUID 258EAFA5-E914-47DA-95CA-C5AB0DC85B11 (the SHA-1 is encoded in base64).
In the example above, the SHA-1 of 2XE8VAJktqi3Tpw5QnfxVQ==258EAFA5-E914-47DA-95CA-C5AB0DC85B11 is PaY9vRflWeOKuD0/F7e5gD9At9U= (in base64).

6.2. Frames

When the client is connected via the websocket protocol:

  • requests and responses are in JSON, inside websocket frames

  • if synchronization is enabled with sync resource, WeeChat can send JSON frames at any time to the client.

Requests to WeeChat are made with a JSON object containing these fields:

  • request (string): the HTTP method and path (example: GET /api/buffers?lines=-100)

  • body (object or array): the body (optional, for POST and PUT methods)

  • request_id (string): identifier sent back in the response

Multiple requests can be sent at once using an array of objects, each object being a separate request.
Requests are executed in the order received (see example below).

Responses to client are made with a JSON object containing these fields:

  • code (integer): HTTP response code (example: 200)

  • message (string): message for the code (example: OK)

  • request (string): the request (example: GET /api/buffers?lines=-100)

  • request_body (object): the request body, or null if the request had no body

  • request_id (string): the request id, or null if the request had no id

  • body_type (string): type of objects returned in body (see below), or null if the response has no body

  • body (object or array): the body returned, or null if the response has no body

Body types that can be returned:

  • handshake (object)

  • version (object)

  • buffers (array)

  • buffer (object)

  • lines (array)

  • line (object)

  • nick_group (object)

  • nick (object)

  • hotlist (object)

  • ping (object)

Tip
 You can browse these schemas online: WeeChat Relay API ↗.

Request example: get version:

{
    "request": "GET /api/version",
    "request_id": "get_version"
}

Response:

{
    "code": 200,
    "message": "OK",
    "request": "GET /api/version",
    "request_body": null,
    "request_id": "get_version",
    "body_type": "version",
    "body": {
        "weechat_version": "4.2.0-dev",
        "weechat_version_git": "v4.1.0-143-g0b1cda1c4",
        "weechat_version_number": 67239936,
        "relay_api_version": "0.0.1",
        "relay_api_version_number": 1
    }
}

Request example: say "hello!" on channel #weechat:

{
    "request": "POST /api/input",
    "body": {
        "buffer_name": "irc.libera.#weechat",
        "command": "hello!"
    }
}

Response:

{
    "code": 204,
    "message": "No Content",
    "request": "POST /api/input",
    "request_body": {
        "buffer_name": "irc.libera.#weechat",
        "command": "hello!"
    },
    "request_id": null,
    "body_type": null,
    "body": null
}

Requests example: send two requests at once: get list of all buffers with lines and nicks, then synchronize with the remote:

[
    {
        "request": "GET /api/buffers?lines=-1000&nicks=true&colors=weechat",
        "request_id": "initial_sync"
    },
    {
        "request": "POST /api/sync",
        "body": {
            "colors": "weechat"
        }
    }
]
Note
 It is recommended to send the synchronization request together with the first request that is fetching data, so that no events are missed.

First response (body with buffers is truncated for readability):

{
    "code": 200,
    "message": "OK",
    "request": "GET /api/buffers?lines=-1000&nicks=true&colors=weechat",
    "request_body": null,
    "request_id": "initial_sync",
    "body_type": "buffers",
    "body": [
        {
            "id": 1709932823238637,
            "name": "core.weechat",
            "short_name": "weechat",
            "number": 1,
            "type": "formatted"
        }
    ]
}

Second response:

{
    "code": 204,
    "message": "No Content",
    "request": "POST /api/sync",
    "request_body": {
        "colors": "weechat"
    },
    "request_id": null,
    "body_type": null,
    "body": null
}

WeeChat pushes data to the client at any time on some events: when lines are displayed, buffers added/removed/changed, nicks added/removed/changed, etc.

The messages sent to client have the following fields:

  • code: 0

  • message: Event

  • event_name (string): the event name (name of signal or hsignal)

  • buffer_id (integer): the buffer unique identifier, set only for sub-objects, -1 in other cases

The following events are sent to the client, according to synchronization options:

Event name Buffer id Body type Body

buffer_opened

buffer id

buffer

buffer with all lines and nicks

buffer_type_changed

buffer id

buffer

buffer

buffer_moved

buffer id

buffer

buffer

buffer_merged

buffer id

buffer

buffer

buffer_unmerged

buffer id

buffer

buffer

buffer_hidden

buffer id

buffer

buffer

buffer_unhidden

buffer id

buffer

buffer

buffer_renamed

buffer id

buffer

buffer

buffer_title_changed

buffer id

buffer

buffer

buffer_time_for_each_line_changed

buffer id

buffer

buffer

buffer_localvar_added

buffer id

buffer

buffer

buffer_localvar_changed

buffer id

buffer

buffer

buffer_localvar_removed

buffer id

buffer

buffer

buffer_cleared

buffer id

buffer

buffer

buffer_closing

buffer id

buffer

buffer

buffer_closed

buffer id

null

null

buffer_line_added

buffer id

line

buffer line

buffer_line_data_changed

buffer id

line

buffer line

input_text_changed

buffer id

buffer

buffer

input_text_cursor_moved

buffer id

buffer

buffer

nicklist_group_changed

buffer id

nick_group

nick group

nicklist_group_added

buffer id

nick_group

nick group

nicklist_group_removing

buffer id

nick_group

nick group

nicklist_nick_added

buffer id

nick

nick

nicklist_nick_removing

buffer id

nick

nick

nicklist_nick_changed

buffer id

nick

nick

upgrade (1)

-1

null

null

upgrade_ended (1)

-1

null

null

quit

-1

null

null
Note
 (1) The events upgrade and upgrade_ended are sent only if the client is connected with plain text (no TLS), because with TLS the client is disconnected before the upgrade is done (upgrade of TLS connections is not supported).

Example: new buffer: channel #weechat has been joined:

{
    "code": 0,
    "message": "Event",
    "event_name": "buffer_opened",
    "buffer_id": 1709932823649069,
    "body_type": "buffer",
    "body": {
        "id": 1709932823649069,
        "name": "irc.libera.#test",
        "short_name": "",
        "number": 4,
        "type": "formatted",
        "hidden": false,
        "title": "",
        "modes": "+nt",
        "input_prompt": "\u001b[92m@\u001b[96malice\u001b[48;5;22m(\u001b[39mi\u001b[48;5;22m)",
        "input": "",
        "input_position": 0,
        "input_multiline": false,
        "nicklist": true,
        "nicklist_case_sensitive": false,
        "nicklist_display_groups": false,
        "time_displayed": true,
        "local_variables": {
            "plugin": "irc",
            "name": "libera.#test",
            "type": "channel",
            "nick": "alice",
            "host": "~alice@example.com",
            "server": "libera",
            "channel": "#test"
        },
        "keys": [],
        "lines": []
    }
}

Example: new line displayed on channel #weechat:

{
    "code": 0,
    "message": "Event",
    "event_name": "buffer_line_added",
    "buffer_id": 1709932823649069,
    "body_type": "line",
    "body": {
        "id": 5,
        "index": -1,
        "date": "2024-01-07T08:54:00.179483Z",
        "date_printed": "2024-01-07T08:54:00.179483Z",
        "displayed": true,
        "highlight": false,
        "notify_level": 0,
        "prefix": "alice",
        "message": "hello!",
        "tags": [
            "irc_privmsg",
            "self_msg",
            "notify_none",
            "no_highlight",
            "prefix_nick_white",
            "nick_alice",
            "log1"
        ]
    }
}

Example: nick bob added with operator status in channel #weechat:

{
    "code": 0,
    "message": "Event",
    "event_name": "nicklist_nick_added",
    "buffer_id": 1709932823649069,
    "body_type": "nick",
    "body": {
        "id": 1709932823649902,
        "parent_group_id": 1709932823649181,
        "prefix": "@",
        "prefix_color_name": "lightgreen",
        "prefix_color": "\u001b[92m",
        "name": "bob",
        "color_name": "bar_fg",
        "color": "",
        "visible": true
    }
}

Example: channel buffer #weechat has been closed:

{
    "code": 0,
    "message": "Event",
    "event_name": "buffer_closed",
    "buffer_id": 1709932823649069,
    "body_type": null,
    "body": null
}

Example: WeeChat is upgrading:

{
    "code": 0,
    "message": "Event",
    "event_name": "upgrade",
    "buffer_id": -1,
    "body_type": null,
    "body": null
}

Example: upgrade of WeeChat is done:

{
    "code": 0,
    "message": "Event",
    "event_name": "upgrade_ended",
    "buffer_id": -1,
    "body_type": null,
    "body": null
}