---
title: "Server API"
canonical_url: https://www.superlogical.com/rex/docs/automate/server-api
---

# 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:

```sh
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](#block-methods), 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](https://json-schema.org). 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 `-`:

```sh
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:

```sh
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`](https://jqlang.org):

```sh
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:

```lua
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:

| API method | Lua |
| --- | --- |
| `session.view` | `rex.session.view{}` |
| `session.set_label` | `rex.session.set_label{ label = "work" }` |
| `session.new_split` | `rex.session.new_split{ ... }` |

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:

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

The [Lua API reference](/content/rex/docs/reference/lua.md#calling-rex/index.html) 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:

```sh
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`:

```sh
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:

```lua
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:

```sh
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.