nomad/website/content/api-docs/operator/raft.mdx

---
layout: api
page_title: Raft - Operator - HTTP API
description: |-
  The /operator/raft endpoints provide tools for management of the Raft subsystem.
---

# Raft Operator HTTP API

The `/operator/raft` endpoints provide tools for management of the Raft subsystem.

Please see the [Consensus Protocol Guide] for more information about Raft consensus protocol and its use.

## Read Raft Configuration

This endpoint queries the status of a client node registered with Nomad.

| Method | Path                              | Produces           |
| ------ | --------------------------------- | ------------------ |
| `GET`  | `/v1/operator/raft/configuration` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `stale` - Specifies if the cluster should respond without an active leader.
  This is specified as a query string parameter.

### Sample Request

<Tabs>
<Tab heading="Nomad CLI">

```shell-session
$ nomad operator api /v1/operator/raft/configuration
```

</Tab>
<Tab heading="curl">

```shell-session
$ curl \
    https://localhost:4646/v1/operator/raft/configuration
```

</Tab>
</Tabs>

### Sample Response

```json
{
    "Index": 0,
    "Servers": [
        {
            "Address": "10.1.0.10:4647",
            "ID": "c13f9998-a0f3-d765-0b52-55a0b3ce5f88",
            "Leader": false,
            "Node": "node1.global",
            "RaftProtocol": "3",
            "Voter": true
        },
        {
            "Address": "10.1.0.20:4647",
            "ID": "d7927f2b-067f-45a4-6266-af8bb84de082",
            "Leader": true,
            "Node": "node2.global",
            "RaftProtocol": "3",
            "Voter": true
        },
        {
            "Address": "10.1.0.30:4647",
            "ID": "00d56ef8-938e-abc3-6f8a-f8ac80a80fb9",
            "Leader": false,
            "Node": "node3.global",
            "RaftProtocol": "3",
            "Voter": true
        }

    ]
}
```

#### Field Reference

- `Index` `(int)` - The `Index` value is the Raft corresponding to this
  configuration. The latest configuration may not yet be committed if changes
  are in flight.

- `Servers` `(array: Server)` - The returned `Servers` array has information
  about the servers in the Raft peer configuration.

  - `ID` `(string)` - The ID of the server. For Raft protocol v2, this is the
    same as the `Address`. Raft protocol v3 uses GUIDs as the ID.

  - `Node` `(string)` - The node name of the server, as known to Nomad, or
    `"(unknown)"` if the node is stale and not known.

  - `Address` `(string)` - The `ip:port` for the server.

  - `Leader` `(bool)` - is either "true" or "false" depending on the server's
    role in the Raft configuration.

  - `Voter` `(bool)` - is "true" or "false", indicating if the server has a vote
    in the Raft configuration. Future versions of Nomad may add support for
    non-voting servers.

## Remove Raft Peer

This endpoint removes a Nomad server with given address from the Raft
configuration. The return code signifies success or failure.

| Method   | Path                     | Produces           |
| -------- | ------------------------ | ------------------ |
| `DELETE` | `/v1/operator/raft/peer` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `id` `(string: <optional>)` - Specifies the Raft **ID** of the server to
  remove as provided in the output of `/v1/operator/raft/configuration`
  API endpoint or the `nomad operator raft list-peers` command.

### Sample Request


<Tabs>
<Tab heading="Nomad CLI">

```shell-session
$ nomad operator api -X DELETE \
   /v1/operator/raft/peer?address=1.2.3.4:4647
```

</Tab>
<Tab heading="curl">

```shell-session
$ curl \
    --request DELETE \
    --header "X-Nomad-Token: ${NOMAD_TOKEN}"
    https://127.0.0.1:4646/v1/operator/raft/peer?address=1.2.3.4:4647
```

</Tab>
</Tabs>

## Transfer Leadership to another Raft Peer

This endpoint tells the current cluster leader to transfer leadership
to the Nomad server with given address or ID in the Raft
configuration. The return code signifies success or failure.

| Method              | Path                                    | Produces           |
| ------------------- | --------------------------------------- | ------------------ |
| `PUT` <br /> `POST` | `/v1/operator/raft/transfer-leadership` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `address` `(string: <optional>)` - Specifies the Raft **Address** of the
  target server as provided in the output of `/v1/operator/raft/configuration`
  API endpoint or the `nomad operator raft list-peers` command.

- `id` `(string: <optional>)` - Specifies the Raft **ID** of the target server
  as provided in the output of `/v1/operator/raft/configuration` API endpoint or
  the `nomad operator raft list-peers` command.

<Note>

- The cluster must be running Raft protocol v3 or greater on all server members.

- Either `address` or `id` must be provided, but not both.

</Note>

### Sample Requests

<Tabs>
<Tab heading="Nomad CLI">

```shell-session
$ nomad operator api -X PUT \
    "/v1/operator/raft/transfer-leadership?address=1.2.3.4:4647"
```

</Tab>
<Tab heading="curl">

```shell-session
$ curl --request PUT \
    --header "X-Nomad-Token: ${NOMAD_TOKEN}"
    "https://127.0.0.1:4646/v1/operator/raft/transfer-leadership?address=1.2.3.4:4647"
```

</Tab>
</Tabs>

[consensus protocol guide]: /nomad/docs/architecture/cluster/consensus