Server API

The server documents its own API. You can list every method, read a method’s arguments and result, and call it, all from the CLI:

rex api list
rex api describe session.new_split
rex api call server.version

Because the documentation comes from the server you are connected to, it always matches that server’s version.

The CLI and Lua APIs all derive dynamically from the server API it is connected to, so these commands are also important for scripting and automation at a higher level.

Discovering Methods

rex api list prints every method with a short description:

$ rex api list
METHOD              DESCRIPTION
block.close         Close a block within a session. ...
block.event         Deliver an external event to a block within a session.
block.method        Invoke a typed method on a block within a session ...
...

A second table lists the methods that blocks provide, such as reading a terminal’s screen.

Use -q to print only the names, which is handy for searching:

$ rex api list -q | grep label
client.set_label
session.set_block_label
session.set_label
session.set_window_label

Reading a Method’s Documentation

rex api describe prints everything the server knows about one method: what it does, the arguments it takes, what it returns, and an example of each.

$ rex api describe session.set_block_label
Update a block's human-readable display label. ...

Method: session.set_block_label

Input schema:
{
  "type": "object",
  "properties": {
    "block_id": { "type": ["string", "null"] },
    "label": { "type": "string" },
    "session_id": { "type": "string" }
  },
  "required": ["session_id"],
  "additionalProperties": false
}

Output schema:
{
  "type": "object",
  "properties": {
    "revision": { "type": "integer", "minimum": 0 }
  },
  "required": ["revision"],
  "additionalProperties": false
}

Request example:
{
  "session_id": "session:<uuid>",
  "block_id": "block:<uuid>",
  "label": "shell"
}

Response example:
{"revision": 42}

The schemas are JSON Schema. To read one:

• properties lists each argument and its type.
• required lists the arguments that must be present.
• additionalProperties: false means a misspelled argument is an error rather than being ignored.

The request example is usually the quickest way to see how a call should look. Some methods also print validation notes, which describe rules the schema can’t express.

Calling a Method

rex api call calls a method and prints its result as JSON:

$ rex api call server.version
{
  "rex_version": "0.1.0",
  "platform": "darwin_arm64",
  ...
}

Arguments are a single JSON object. Pass it directly, read it from a file with @, or read it from stdin with -:

rex api call -s work session.set_label '{"label": "api"}'
rex api call session.create @layout.json
echo '{"label": "work"}' | rex api call session.create -

Most session. methods need a session_id. Name the session with -s and rex api call adds it to the arguments for you:

rex api call -s work session.view

Unlike other rex commands, rex api call doesn’t default to the session you are in. Inside a Rex terminal, pass -s "$REX_SESSION" to use it.

Other IDs are never filled in. A method that acts on a block needs its block_id in the arguments.

The result is indented when printed to a terminal and kept on one line when piped, so it is ready for jq:

rex api call -s work session.view | jq '.windows | length'

Errors

A call that fails prints the server’s message and exits with a nonzero status:

$ rex api call -s work session.set_block_label '{"lable": "x"}'
Error: ... input: validating: block_id is required (status=400 code=bad_request)

The code says what kind of failure it was. bad_request means the arguments were wrong, and method_not_found means the server has no method by that name, which can happen when the server is older than the docs you are reading.

Calling From Lua

rex.call takes a method’s full name and its arguments as a table:

local version = rex.call("server.version")
print(version.rex_version)

Every session. method that acts on one session also has a helper under rex.session, named after the method:

The arguments and result are the same as rex api describe shows, written as Lua tables instead of JSON. The helpers fill in session_id when it is left out. rex.call doesn’t, so pass rex.session_id yourself when calling a session. method through it.

A few session. methods have no helper because they don’t act on an existing session, such as session.list and session.create. Call those with rex.call.

A failed call returns nil and the server’s error message:

local result, err = rex.session.set_block_label{ lable = "x" }
if err ~= nil then error(err, 0) end

The Lua API reference covers these functions in full.

Block Methods

Blocks provide methods of their own. rex api list prints them in a second table, named for the kind of block that provides them:

Block methods:
CREATOR                    METHOD                             DESCRIPTION
com.superlogical.terminal  com.superlogical.terminal.format   Format the current terminal screen ...
com.superlogical.terminal  com.superlogical.terminal.pwd      Return the working directory ...
com.superlogical.terminal  com.superlogical.terminal.title    Return the current terminal title.
...

Describe one the same way as any other method:

rex api describe com.superlogical.terminal.format

To call one, pass the block_id to call it on, and put the method’s own arguments under args:

rex api call -s work com.superlogical.terminal.format \
  '{"block_id": "block:01a1...", "args": {"trim": true}}'

In Lua, rex.block.call builds that wrapper for you and fills in the current block:

local terminal = "com.superlogical.terminal"
local screen = rex.block.call(terminal, "format", { trim = true })
print(screen.content)

Machine-Readable Documentation

Both discovery commands take --json, which prints the server’s own description of its API:

rex api list --json       # every method, with schemas and examples
rex api describe session.view --json

Each method has a name, a description, an input_schema, an output_schema, and, where the server has them, a request_example, a response_example, and validation_notes.

This is useful for generating bindings, for checking a script against a server before running it, and for giving a coding agent the exact shape of the API it is about to call.