Runtimes, cluster and operations API

See the API overview for authentication, errors and how operations work.

Runtimes

A runtime is a database engine version, written engine@version (mysql@8.4.13, postgres@18.6).

GET /v1/runtimes

Action runtime.read. Lists the runtimes installed on this node. Add ?node=<name> to ask another node.

{ "items": [ { "runtime": "postgres@18.6", "engine": "postgres", "version": "18.6" } ], "next_cursor": null }

GET /v1/runtimes/available

Action runtime.read. Lists the MySQL and PostgreSQL versions the package catalog offers for this node. Same item shape.

POST /v1/runtimes

Action runtime.install. Installs a runtime. In a cluster it is recorded for every node and installed on all of them, and new nodes install it when they join. Answers 202, operation kind runtime.install.

{ "runtime": "postgres@18.6" }

Errors: 422 runtime_unavailable (not in the catalog), 409 already_exists.

DELETE /v1/runtimes/{engine}/{version}

Action runtime.remove. Removes the runtime, for example DELETE /v1/runtimes/postgres/18.6. In a cluster it is removed from every node. With ?node=<name> only that node is affected. Answers 204. If a base or branch uses it, or a node is down, the answer is 409 in_use and names the nodes.

Cluster and nodes

GET /v1/cluster

Action cluster.read. Returns the cluster as this node sees it. A single node reports "mode": "single".

{
  "mode": "cluster",
  "leader": "node1",
  "protocol": 3,
  "nodes": [
    {
      "name": "node1", "host": "node1", "address": "10.0.0.1:7070", "version": "1.4.0",
      "leader": true, "voter": true, "down": false, "last_seen": "2026-11-09T12:00:00Z",
      "pool_size": 1000000000000, "pool_free": 640000000000,
      "runtimes": ["postgres@18.6"], "modules": ["auth 1.4.0"],
      "metrics": { "time": "2026-11-09T12:00:00Z", "cpu": 12.5, "load1": 0.4, "mem_total": 17179869184, "mem_used": 6442450944, "net_rx": 1200, "net_tx": 800, "arc": 2147483648 },
      "arc_max_mb": 4096
    }
  ]
}

A node that is down has down: true. voter says whether the node votes on cluster changes. arc_problem appears when the ZFS cache limit could not be applied.

GET /v1/nodes/{name}/metrics

Action cluster.read. Returns the node’s recent performance samples (CPU, load, memory, network, ZFS cache), oldest first, as {"items": [...]}. The console draws its last-hour charts from this.

GET /v1/metrics

Action metrics.read. Prometheus text format (text/plain; version=0.0.4) for this node: cluster and node state, branches, bases, replication, module problems and API request counts.

POST /v1/cluster/token

Action cluster.token. Creates a token for joining a node to the cluster. Works only over a node’s local socket (db-branch cluster token); over HTTPS it returns 403 socket_only, and on a node that is not clustered 409 not_clustered.

GET /v1/capabilities

Action capability.read. Returns this node’s version and the modules it runs, plus the console pages that modules add.

{ "version": "1.4.0", "node": "node1", "modules": ["auth 1.4.0"], "pages": [] }

Operations

GET /v1/operations

Action operation.read. Lists operations, newest first. Finished operations are kept up to the newest 200.

GET /v1/operations/{id}

Action operation.read. Returns one operation. Without a login this works for operations started by an anonymous branch creation. Unknown IDs return 404 not_found. The fields are described in the overview.

The kinds you will see are branch.create, branch.reset, branch.recreate, branch.delete, base.create, base.snapshot, base.mask, base.load, base.refresh and runtime.install.

Events

GET /v1/events

Action event.read. The Server-Sent Events stream described in the overview.