---
title: "Cluster: Cluster API"
description: "Use the RavenDB cluster API to add, remove, promote, and demote cluster nodes and manage cluster leadership."
url: "https://docs.ravendb.net/6.2/server/clustering/cluster-api"
version: "6.2"
---

# Cluster: Cluster API

> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

## Cluster: Cluster API

> **Note**
>
> - You can manage a RavenDB cluster using Studio's [Cluster View](https://docs.ravendb.net/6.2/studio/cluster/cluster-view.md).  
>   All cluster operations can be performed through Studio. However, you may sometimes prefer to automate these operations.
>
> - In this article, we demonstrate several cluster operations you can perform using the REST API.  
>   The first example shows how to make a secure call using PowerShell, cURL, and the RavenDB C# client.  
>   All other examples are cURL only.
>
> - If authentication is enabled, each call must present a client certificate with the [security clearance](https://docs.ravendb.net/6.2/server/security/authorization/security-clearance-and-permissions.md)
>   required by its endpoint: `Cluster Admin` for most operations, and `Operator` for [Force elections](#force-elections) and [Force timeout](#force-timeout).
>
> - In this article:
>   - [REST API endpoints](#rest-api-endpoints)
>     - [Add node to the cluster](#add-node-to-the-cluster)
>     - [Delete node from the cluster](#delete-node-from-the-cluster)
>     - [Promote a node](#promote-a-node)
>     - [Demote a node](#demote-a-node)
>     - [Bootstrap cluster](#bootstrap-cluster)
>     - [Force elections](#force-elections)
>     - [Force timeout](#force-timeout)

## REST API endpoints {#rest-api-endpoints}

Each operation below is performed by calling a REST endpoint.

### Add node to the cluster

You can add a node to the cluster by sending an `HTTP PUT` request to the `/admin/cluster/node` endpoint with the following arguments:

| Argument | Description | Required | Default |
| - | - | - | - |
| `new-node-url` | The address of the new node you want to add to the cluster | `true` | - |
| `new-node-tag` | 1-4 uppercase unicode letters | `false` | `A` - `Z` assigned by order of addition |
| `is-watcher` | Add the new node as a [watcher](https://docs.ravendb.net/6.2/server/clustering/rachis/cluster-topology.md#watcher) | `false` | `false` |
| `max-utilized-cores` | The maximum number of cores that can be assigned to the new node | `false` | Number of processors on the machine or the license limit, the smaller of the two |

> **Info**
>
> Required security clearance: `Cluster Admin`

#### Example: Add a node

##### C\#

To make a secure call, the Document Store must be provided with the client certificate (see [example](https://docs.ravendb.net/6.2/client-api/setting-up-authentication-and-authorization.md#example---initializing-document-store-with-a-client-certificate)).

```csharp
store.GetRequestExecutor().HttpClient.SendAsync(new HttpRequestMessage(HttpMethod.Put, "https://<server-url>/admin/cluster/node?url=<new-node-url>&tag=<new-node-tag>&watcher=<is-watcher>&maxUtilizedCores=<max-utilized-cores>"));
```

##### PowerShell

To make a secure call, load the client certificate from a PFX file and pass it to the request.

```powershell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$clientCert = Get-PfxCertificate -FilePath <path-to-pfx-cert>
Invoke-WebRequest -Method Put -URI "https://<server-url>/admin/cluster/node?url=<new-node-url>&tag=<new-node-tag>&watcher=<is-watcher>&maxUtilizedCores=<max-utilized-cores>" -Certificate $clientCert
```

##### cURL

To make a secure call, provide the client certificate and private key using the `--cert` and `--key` options.

```bash
curl --cert <path-to-cert> --key <path-to-key> -X PUT "https://<server-url>/admin/cluster/node?url=<new-node-url>&tag=<node-tag>&watcher=<is-watcher>&maxUtilizedCores=<max-utilized-cores>"
```

### Delete node from the cluster

You can delete a node from the cluster by sending an `HTTP DELETE` request to the `/admin/cluster/node` endpoint with the following argument:

| Argument | Description | Required | Default |
| - | - | - | - |
| `node-tag` | The tag of the node to delete | `true` | - |

> **Info**
>
> Required security clearance: `Cluster Admin`

> **Warning:** Check the replication factor before removing a node
>
> Removing a node removes from the cluster the database copies this node held:
>
> - A database whose only copy was on the removed node **will become inaccessible**.
> - A multi-node database that had one of its copies on the removed node will have its [replication factor](https://docs.ravendb.net/6.2/glossary/replication-factor.md) reduced by one.
>
> **Prior to removing a node, make sure that all the databases it holds have copies on other nodes.**

#### Example: Delete a node

```bash
curl -X DELETE "https://<server-url>/admin/cluster/node?nodeTag=<node-tag>"
```

### Promote a node

[Promoting a node](https://docs.ravendb.net/6.2/server/clustering/rachis/cluster-topology.md#nodes-states-and-types) turns a watcher into a voting member that participates in the cluster quorum.  
You can promote a node by sending an `HTTP POST` request to the `/admin/cluster/promote` endpoint with the following argument:

| Argument | Description | Required | Default |
| - | - | - | - |
| `node-tag` | The tag of the node to promote | `true` | - |

> **Info**
>
> - No request body is required.
> - Required security clearance: `Cluster Admin`

#### Example: Promote a node

```bash
curl -X POST "https://<server-url>/admin/cluster/promote?nodeTag=<node-tag>" -d ''
```

### Demote a node

[Demoting a node](https://docs.ravendb.net/6.2/server/clustering/rachis/cluster-topology.md#nodes-states-and-types) turns a voting member into a watcher that no longer participates in the cluster quorum.  
You can demote a node by sending an `HTTP POST` request to the `/admin/cluster/demote` endpoint with the following argument:

| Argument | Description | Required | Default |
| - | - | - | - |
| `node-tag` | The tag of the node to demote | `true` | - |

> **Info**
>
> - No request body is required.
> - Required security clearance: `Cluster Admin`

#### Example: Demote a node

```bash
curl -X POST "https://<server-url>/admin/cluster/demote?nodeTag=<node-tag>" -d ''
```

### Bootstrap cluster

You can bootstrap the cluster by sending an empty `HTTP POST` request to the `/admin/cluster/bootstrap` endpoint.  
Note that bootstrapping takes effect only while the server is in the [Passive state](https://docs.ravendb.net/6.2/server/clustering/rachis/cluster-topology.md#nodes-states-and-types). On a server that has already formed or joined a cluster, the request has no effect.

> **Info**
>
> Required security clearance: `Cluster Admin`

#### Example: Bootstrap the cluster

```bash
curl -X POST "https://<server-url>/admin/cluster/bootstrap" -d ''
```

### Force elections

You can force an election by sending an empty `HTTP POST` request to the `/admin/cluster/reelect` endpoint.

> **Info**
>
> Required security clearance: `Operator`

#### Example: Force an election

```bash
curl -X POST "https://<server-url>/admin/cluster/reelect" -d ''
```

### Force timeout

You can force a timeout by sending an empty `HTTP POST` request to the `/admin/cluster/timeout` endpoint.

> **Info**
>
> Required security clearance: `Operator`

#### Example: Force a timeout

```bash
curl -X POST "https://<server-url>/admin/cluster/timeout" -d ''
```
