User Interface API

User Interface API

These user interface API validates the requests from clients with JWT based authentication.

User Authenticate


POST /web/api/login

Refresh token

POST /web/api/relogin


POST /web/api/logout

  • LogoutReq:
    "refreshToken": "refresh token that was issued with 'login'"


GET /web/api/check

Validates current token status.

  • LoginCheckRsp
    "success": true,
    "reason": "string",
    "elapse": "string",
    "experimentMode": false,
    "server": {"version":"v1.2.3"},
    "shells": [{"ShellDefinition"}]
  • ShellDefinition
    "id": "shell definition id (uuid)",
    "type": "type",
    "icon": "icon name",
    "label": "display name",
    "theme": "theme name",
    "command": "terminal shell command",
    "attributes": [
        { "removable": true },
        { "cloneable": true },
        { "editable": true }
  • types
sqlsql editor
tqltql editor
wrkworkspace editor
taztag analyzer


Execute SQL

GET,POST /web/machbase

It works as same as /db/query API, the only difference is the way of authentication. The /db/query authorize the client applications by API Token, while /web/machbase validates JWT for user interactions.

List tables

GET /web/api/tables?showall=false&name=pattern

Return table list

  • showall returns includes all hidden tables if set true
  • name table name filtering pattern, the pattern can be a glob (includes ? or *) or prefix (which has no ? and *)
    "success": true,
    "reason": "success or other message",
    "elapse": "elapse time in string format",
    "data": {
        "columns": ["ROWNUM", "DB", "USER", "NAME", "TYPE"],
        "types": ["int32", "string", "string", "string", "string"],
            [1, "MACHBASE", "SYS", "TABLENAME", "TAG TABLE"],

List tags

GET /web/api/tables/:table/tags?name=prefix

Returns tag list of the table

  • name returns only tags those name starts with the given prefix
    "success": true,
    "reason": "success or other message",
    "elapse": "elapse time in string format",
    "data": {
        "columns": ["ROWNUM", "NAME"],
        "types": ["int32", "string"],
            [1, "temperature"],

Tag stat

GET /web/api/tables/:table/:tag/stat

Returns the stat of tag of the table

    "success": true,
    "reason": "success or other message",
    "elapse": "elapse time in string format",
    "data": {
        "columns": ["ROWNUM", "NAME", "ROW_COUNT", "MIN_TIME", "MAX_TIME",
        "types": ["int32", "string", "int64", "datetime", "datetime","double", 
            "datetime", "double", , "datetime",, "datetime"],

Shell & Terminal

Data channel


Web socket for terminal

Window size

POST /web/api/term/:term_id/windowsize

Change terminal size


{ "rows": 24, "cols": 80 }

Get Shell Definition

GET /web/api/shell/:id

Returns ShellDefinition for the given id

Update Shell Definition

POST /web/api/shell/:id

Update the ShellDefinition of the given id

Make copy of Shell

GET /web/api/shell/:id/copy

Returns ShellDefinition for a new copy of the shell of the given id

Delete Shell Definition

DELETE /web/api/shell/:id

Delete the shell of the given id

    "success": true,
    "reason": "success of error message",
    "elapse": "time represents in text"

Server events

Event channel


Web socket for the bi-directional messages

  • message type
    "type": "type(see below)",
    "ping": {
        "tick": 1234
    "log": {
        "level": "INFO",
        "message": "log message"
pingping message
ping.tickany integer number, server will respond with the same number that client sends
loglog.levellog level TRACE, DEBUG, INFO, WARN, ERROR
log.messagelog message
log.repeatcount, if the same message repeats more than two times in serial

TQL & Workspace

Content-types of TQL

text/html“echart”Full HTML (echart)
ex) It may be inside of <iframe>
text/html-Full HTML
ex) It may be inside of <iframe>
application/json“echart”JSON (echart data)
application/xhtml+xml-HTML Element, ex) <div>...</div>

Run tql file

GET /web/api/tql/*path

Run the tql of the path, refer the section of ‘Content-types of TQL’ for the response

POST /web/api/tql/*path

Run the tql of the path, refer the section of ‘Content-types of TQL’ for the response

Run tql script

POST /web/api/tql

Post tql script as content payload, server will response the execution result. refer the section of ‘Content-types of TQL’ for the response

Markdown rendering

POST /web/api/md

Post markdown as content payload, sever will response the rendering result in xhtml

File management


File types and content-type

file typeContent-Type

Read file

GET /web/api/files/*path

Returns the content of the file if the path is pointing a file.

Returns Dir entries if the path is pointing a directory.

  • Entry
    "isDir": true,
    "name": "name",
    "content": "bytes array, if the entry is a file",
    "children": [{"SubEntry, if the entry is a directory"}],
  • SubEntry
    "isDir": true,
    "name": "name",
    "type": "type",
    "size": 1234,
    "lastModifiedUnixMillis": 169384757

Write file

POST /web/api/files/*path

  • if the path points a file, it will write the payload content into the file.

  • if the path is a directory and request with no content, it will create a empty directory. and returns the Entry of the directory

  • if the path is a directory and payload is json of GitCloneReq, it will clone the remote git repository to the path and returns Entry of the directory.


    "command": "clone",
    "url": ""
  • command : clone, pull

Rename/move file

PUT /web/api/files/*path

Rename(move) a file (or a directory).


    "destination": "target path",

This api returns status code 200 OK if the operation has done successfully.

Remove file

DELETE /web/api/files/*path

Delete the file at the path, if the path is pointing a directory and is not empty, it will return error.



GET /web/api/refs/*path

  • ReferenceGroup
    "label": "group name",
  • ReferenceItem
    "type": "type",
    "title": "display title",
    "address": "url address",
    "target": "browser link target"
  • type: url, wrk, tql, sql
  • address: if address has prefix serverfile://<path> it points a server side file, otherwise external web url that starts with https://

License info

GET /web/api/license

    "success": true,
    "reason": "success or error reason",
    "elapse": "elapse time",
    "data": {
        "id": "license id",
        "type": "type",
        "customer": "customer",
        "project": "project",
        "countryCode": "country code",
        "installDate": "installation date",
        "issueDate": "license issue date"

License install

POST /web/api/license

Install license file

Last updated on