HTTP API Reference

The plugin's API is what the Branches tab uses, and what an agent, a CI job or a script can call to branch databases without kubectl access to the cluster. Every request is authorized against OpenEverest RBAC as the caller.

The API only creates, lists and deletes the plugin's custom resources; the controller does the work. A call returns as soon as the resource is created: poll GET /api/branches until the branch is Ready.

Base URL and authentication

The OpenEverest server serves the plugin under:

https://<everest-host>/v1/clusters/{cluster}/plugins/plugin-branching

{cluster} is the Kubernetes cluster's name in OpenEverest, main by default. Pass an OpenEverest API token in the Authorization header, and the instance in the query string of every endpoint:

Query parameter	Description
`namespace`	Required. The instance's namespace.
`instance`	Required. The instance's name.

export EVEREST=https://everest.example.com/v1/clusters/main/plugins/plugin-branching
export TOKEN=...   # an OpenEverest API token

curl -s -H "Authorization: Bearer $TOKEN" \
  "$EVEREST/api/branches?namespace=team-a&instance=orders"

Endpoints

Endpoint	Body	Returns
`GET /api/branches`		`200` `{branches, canManage, instance?, instanceError?, restorePoints, operations}`
`POST /api/branches`	Clone: `{name, sourceDatabase, database?, sourceConnections?}`; Snapshot: `{name, method: "Snapshot", instanceName?}`	`201` branch
`DELETE /api/branches/{name}`		`204`
`POST /api/branches/{name}/reset`		`201` operation
`POST /api/branches/{name}/promote`		`201` operation
`POST /api/restore-points`	`{name?, method?, database?}`	`201` restore point
`DELETE /api/restore-points/{name}`		`204`
`POST /api/restore-points/{name}/rollback`		`201` operation

List branches

GET /api/branches returns the instance's branches, its restore points, its ten most recent operations (newest first), and what can be branched.

{
  "canManage": true,
  "instance": {
    "serverVersion": "18.6",
    "supported": true,
    "replicas": 1,
    "replicasCopyOnWrite": true,
    "databases": [
      { "name": "app", "owner": "app", "sizeBytes": 10737418240, "branchable": true },
      { "name": "app_feature_x", "owner": "app", "branchable": true, "branch": true },
      { "name": "postgres", "owner": "postgres", "branchable": false, "reason": "system database" }
    ],
    "methods": [
      { "method": "Clone", "supported": true },
      { "method": "Snapshot", "supported": true }
    ]
  },
  "branches": [
    {
      "name": "feature-x",
      "method": "Clone",
      "sourceDatabase": "app",
      "database": "app_feature_x",
      "sourceConnections": "Terminate",
      "deletionPolicy": "Delete",
      "phase": "Ready",
      "owner": "app",
      "createdAt": "2026-11-10T13:20:01Z",
      "copyMethod": "clone",
      "duration": "412ms",
      "terminatedConnections": 1,
      "replicasCopyOnWrite": true,
      "creationTimestamp": "2026-11-10T13:20:00Z"
    }
  ],
  "restorePoints": [
    {
      "name": "before-migration",
      "method": "Snapshot",
      "phase": "Ready",
      "createdAt": "2026-11-11T17:28:47Z",
      "duration": "8.94s",
      "snapshots": 2,
      "creationTimestamp": "2026-11-11T17:28:38Z"
    }
  ],
  "operations": [
    {
      "name": "promote-agent-18-7k2mq",
      "type": "Promote",
      "branch": "agent-18",
      "phase": "Succeeded",
      "startedAt": "2026-11-11T17:29:37Z",
      "completedAt": "2026-11-11T17:29:39Z",
      "duration": "2.431s",
      "safetyRestorePoint": "orders-before-agent-18-b54a14",
      "creationTimestamp": "2026-11-11T17:29:37Z"
    }
  ]
}

Field	Description
`canManage`	Whether the caller may create and delete branches.
`instance`	The instance, when the plugin could read it; otherwise `instanceError` says why.
`instance.supported`, `unsupportedReason`	Whether the instance can be branched at all.
`instance.databases[]`	`{name, owner, sizeBytes?, branchable, reason?, branch?}`: the databases a `Clone` branch can be made of, and why not. `branch` marks branch databases.
`instance.replicas`, `replicasCopyOnWrite`	Standbys, and whether they clone branches too. See Replicas.
`instance.methods[]`	`{method, supported, reason?, details?}`: which methods can branch this instance, and why not.
`branches[]`	The branches, with their spec and status. A Snapshot branch has `instanceName` and `snapshotSource` instead of the database fields. `deleting` is set while it's being deleted.
`restorePoints[]`	`{name, method, database?, phase, message?, createdAt?, duration?, snapshots?, creationTimestamp, deleting?}`.
`operations[]`	`{name, type, branch?, restorePoint?, phase, message?, startedAt?, completedAt?, duration?, safetyRestorePoint?, creationTimestamp}`. `safetyRestorePoint` is the restore point a `Promote` took first.

Create a branch

A database branch (Clone, the default):

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$EVEREST/api/branches?namespace=team-a&instance=orders" \
  -d '{"name": "agent-19", "sourceDatabase": "app"}'

Field	Default	Description
`name`	—	Required. The Branch's name: lowercase letters, digits and hyphens.
`method`	`Clone`	`Clone` or `Snapshot`.
`sourceDatabase`	—	Required for `Clone`. The database to branch.
`database`	`<sourceDatabase>_<name>`	The branch database, for `Clone`. Hyphens in `name` become underscores.
`sourceConnections`	`Terminate`	`Terminate` or `Fail`, for `Clone`.
`instanceName`	`<instance>-<name>`	The branch Instance, for `Snapshot`.

An instance branch (Snapshot):

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$EVEREST/api/branches?namespace=team-a&instance=orders" \
  -d '{"name": "pr-142", "method": "Snapshot"}'

Branches created through the API have deletionPolicy: Delete.

Create a restore point

curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "$EVEREST/api/restore-points?namespace=team-a&instance=orders" \
  -d '{"name": "before-migration"}'

Field	Default	Description
`name`	`<instance>-<timestamp>`	The RestorePoint's name.
`method`	`Snapshot` when the instance supports it, else `Clone`	`Snapshot` keeps the whole instance; `Clone` keeps one `database`.
`database`	—	Required for `Clone`. The database to keep.

Reset, promote and rollback

# Reset a branch to a fresh copy of its source
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  "$EVEREST/api/branches/agent-19/reset?namespace=team-a&instance=orders"

# Promote it: the source gets the branch's data, after a restore point
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  "$EVEREST/api/branches/agent-19/promote?namespace=team-a&instance=orders"

# Roll back to a restore point
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  "$EVEREST/api/restore-points/before-migration/rollback?namespace=team-a&instance=orders"

Each returns 201 with the Operation it created. A branch that is promoted or isn't ready yet returns 409.

Errors

Errors are JSON: {"error": "..."}.

Status	When
`400`	Invalid parameters or body, or a method the instance doesn't support.
`401`	No token.
`403`	The caller lacks a permission below.
`404`	The instance, branch or restore point doesn't exist; the provider isn't supported; or the cluster isn't the one the plugin runs in.
`409`	The name, database or instance name is taken; the branch is promoted or not ready; or an unfinished operation uses it.
`502`	The OpenEverest API couldn't be reached.

Permissions

UI and HTTP API

The plugin checks OpenEverest RBAC as the caller, through the Everest API:

Action	Requires (OpenEverest RBAC)
See the Branches tab	access to the plugin: `p, <role>, plugins, *, <cluster>/plugin-branching`
List branches	`read` on the instance
Create and delete branches	`read-connection` on the instance: a branch copies the source's data, which whoever can read the instance's credentials can already do
Create a Snapshot branch	also the right to create its Instance, which is `create` on instances and `read` on the provider (`providers`, `<cluster>/<provider>`), checked with a dry run as the caller (which also runs the provider's admission checks)
Delete a Snapshot branch	also the right to delete its Instance: the plugin deletes it through the Everest API as the caller
Reset a branch, create a restore point	`read-connection` on the instance; resetting a Snapshot branch also the right to update its Instance
Promote a branch, roll back, delete a restore point	also the right to update the instance, checked with a dry run as the caller: its data is replaced, or the copy of its data from before is

kubectl and GitOps

With kubectl, Kubernetes RBAC on branches, restorepoints and operations applies instead. A Snapshot Branch has the plugin create an Instance, and an Operation replaces an instance's data, so grant them like instances:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: branch-manager
  namespace: team-a
rules:
  - apiGroups: ["plugin-branching.plugins.openeverest.io"]
    resources: ["branches", "restorepoints", "operations"]
    verbs: ["get", "list", "watch", "create", "delete"]

In the database

The plugin uses neither the superuser nor the application owner. For PostgreSQL it declares a role, oe_branching, with a CloudNativePG DatabaseRole named <cluster>-oe-branching:

CREATEDB;
membership in pg_signal_backend (to disconnect the source's sessions) and pg_checkpoint;
membership in the owners of the databases it branches.

Its password is generated into the Secret <cluster>-oe-branching. Databases owned by superusers or operator roles, and postgres, template0 and template1, can't be branched. Branch databases aren't CloudNativePG Database resources, because the operator can't clone.

Base URL and authentication​

Endpoints​

List branches​

Create a branch​

Create a restore point​

Reset, promote and rollback​

Errors​

Permissions​

UI and HTTP API​

kubectl and GitOps​

In the database​