This is a more in depth view of the socket protocol used for communication with ThingsDB. In case you just want to use ThingsDB using one of the language bindings, then this info can be skipped. If you plan to implement your own connector, then this info might be useful to you.

This section applies to communication with ThingsDB over a socket, either by using TCP or a UNIX PIPE connection. Once a connection is made, packages can be send to ThingsDB. Each package starts with a 8 bytes header using little endian, followed by optional data. Before you can send queries to ThingsDB, the connection must be authenticated. This can be done by sending an AUTH package.


LEN (Unsigned, 32bit)

Length of the data, stored as Unsigned, 32-bit, Little Endian. The header size is not included in the length.

Id (16bit)

The Id can be used as an identifier of your package. When ThingsDB send a response on a request, it will use the same Id so this allows you to map a response to a request. This is useful if you want to send multiple requests in parallel. It needs to be stored as 16-bit, Little Endian.

TYPE (Unsigned, 8bit)

Package type is used to describe what kind of package is transmitted.

Request type

Type Number Description
PING 32 Ping, useful as keep-alive.
AUTH 33 Authorization., expects: [username, password] or a token_string.
QUERY 34 Query ThingsDB.
RUN 37 Run a procedure, see procedures for more info.
JOIN 38 Join one or more room(s).
LEAVE 39 Leave one or more room(s).
EMIT 40 Emit an event to a room.
CHK (Unsigned, 8bit)

Inverse of the type: type ^ 0xff. This is used as a check-bit.


Data serialized using MessagePack.

Package format:

│ LEN (4)   │ Id (2)    │ TYPE (1)  │ CHK (1)   │ DATA (..) │

Response type

ThingsDB can respond with one of the following response type:

Type Number Description
PONG 16 Success response to PING (header only).
OK 17 Success response to AUTH and EMIT (header only).
DATA 18 Success response to QUERY, RUN, JOIN and LEAVE (with data).
ERROR 19 Error response (with data).


As an example we create an authentication package for the default admin user with password pass.

This is the package data for our authentication request:

["admin", "pass"]

Serializing the above using MessagePack results in the following 12 bytes:


Now we create the header. For this example we just use Id 0:

  • Data length (12) \x0c\x00\x00\x00
  • Identifier (0) \x00\x00
  • Auth package type (33) \x21
  • Inverse type check bit (222) \xde

So our total package will be:


More examples

Some more examples: