title: LDAP mappings requests

summary: LDAP mappings requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-ldap_mappings) | `/v1/ldap_mappings` | Get all LDAP mappings |
| [GET](#get-ldap_mapping) | `/v1/ldap_mappings/{uid}` | Get a single LDAP mapping |
| [PUT](#put-ldap_mapping) | `/v1/ldap_mappings/{uid}` | Update an LDAP mapping |
| [POST](#post-ldap_mappings) | `/v1/ldap_mappings` | Create a new LDAP mapping |
| [DELETE](#delete-ldap_mappings) | `/v1/ldap_mappings/{uid}` | Delete an LDAP mapping |

title: Get all LDAP mappings {#get-all-ldap_mappings}

text:
GET /v1/ldap_mappings

Get all LDAP mappings.

#### Required permissions

| Permission name |
|-----------------|
| [view_all_ldap_mappings_info]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/ldap_mappings

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-all-response}

text:
Returns a JSON array of [LDAP mapping objects]().

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get LDAP mapping {#get-ldap_mapping}

text:
GET /v1/ldap_mappings/{int: uid}

Get a specific LDAP mapping.

#### Required permissions

| Permission name |
|-----------------|
| [view_ldap_mapping_info]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/ldap_mappings/1

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The object's unique ID. |

title: Response {#get-response}

text:
Returns an [LDAP mapping object]().

#### Example JSON body

[code example]

title: Error codes {#get-error-codes}

text:
Possible `error_code` values:

| Code | Description |
|------|-------------|
| unsupported_resource | The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version.|
| ldap_mapping_not_exist | An object does not exist|

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success. |
| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Operation is forbidden. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | ldap_mapping does not exist. |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support LDAP mappings yet. |

title: Update LDAP mapping {#put-ldap_mapping}

text:
PUT /v1/ldap_mappings/{int: uid}

Update an existing ldap_mapping object.

#### Required permissions

| Permission name |
|-----------------|
| [update_ldap_mapping]() |

title: Request {#put-request}

text:
#### Example HTTP request

	PUT /v1/ldap_mappings/17

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

Include an [LDAP mapping object]() with updated fields in the request body.

title: Response {#put-response}

text:
#### Example JSON body

[code example]

title: Error codes {#put-error-codes}

text:
Possible `error_code` values:

| Code | Description |
|------|-------------|
| unsupported_resource | The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version.|
| name_already_exists | An object of the same type and name exists|
| ldap_mapping_not_exist | An object does not exist|
| invalid_dn_param | A dn parameter has an illegal value|
| invalid_name_param | A name parameter has an illegal value|
| invalid_role_uids_param | A role_uids parameter has an illegal value|
| invalid_account_id_param | An account_id parameter has an illegal value|

title: Status codes {#put-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, LDAP mapping is created. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to change a non-existing LDAP mapping. |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support LDAP mapping yet. |

title: Create LDAP mapping {#post-ldap_mappings}

text:
POST /v1/ldap_mappings

Create a new LDAP mapping.

#### Required permissions

| Permission name |
|-----------------|
| [create_ldap_mapping]() |

title: Request {#post-request}

text:
#### Example HTTP request

	POST /v1/ldap_mappings

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

Include an [LDAP mapping object]() in the request body.

title: Response {#post-response}

text:
#### Example JSON body

[code example]

title: Error codes {#post-error-codes}

text:
Possible `error_code` values:

| Code | Description |
|------|-------------|
| unsupported_resource | The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version.|
| name_already_exists | An object of the same type and name exists|
| missing_field | A needed field is missing|
| invalid_dn_param | A dn parameter has an illegal value|
| invalid_name_param | A name parameter has an illegal value|
| invalid_role_uids_param | A role_uids parameter has an illegal value|

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, an LDAP-mapping object is created. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support LDAP mappings yet. |

title: Delete LDAP mapping {#delete-ldap_mappings}

text:
DELETE /v1/ldap_mappings/{int: uid}

Delete an LDAP mapping object.

#### Required permissions

| Permission name |
|-----------------|
| [delete_ldap_mapping]() |

title: Request {#delete-request}

text:
#### Example HTTP request

	DELETE /v1/ldap_mappings/1

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The ldap_mapping unique ID. |

title: Response {#delete-response}

text: Returns a status code. If an error occurs, the response body may include a more specific error code and message.

title: Error codes {#delete-error-codes}

title: Status codes {#delete-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, the ldap_mapping is deleted. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The request is not acceptable. |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support LDAP mappings yet. |

section_id: response-get-all-response

dn: OU=ops,DC=redislabs,DC=com

section_id: request-post-request

section_id: response-post-response


title: License requests

summary: License requests

page_type: content

title: Overview

role: overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-license) | `/v1/license` | Get license details |
| [PUT](#put-license) | `/v1/license` | Update the license |

title: Get license {#get-license}

role: content

text:
GET /v1/license

Returns the license details, including license string, expiration,
and supported features.

#### Required permissions

| Permission name |
|-----------------|
| [view_license]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/license

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-response}

role: returns

text:
Returns a JSON object that contains the license details:

| Name | Type/Value | Description |
|------|------------|-------------|
| license | string | License data |
| cluster_name | string | The cluster name (FQDN) |
| expired | boolean | If the cluster key is expired (`true` or `false`) |
| activation_date | string | The date of the cluster key activation |
| expiration_date | string | The date of the cluster key expiration |
| key | string | License key |
| features | array of strings | Features supported by the cluster |
| owner | string | License owner |
| shards_limit | integer | The total number of shards allowed by the cluster key |
| ram_shards_limit | integer | The number of RAM shards allowed by the cluster key (as of v7.2) |
| ram_shards_in_use | integer | The number of RAM shards in use |
| flash_shards_limit | integer | The number of flash shards (Auto Tiering) allowed by the cluster key (as of v7.2) |
| flash_shards_in_use | integer | The number of flash shards in use |

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | License is returned in the response body. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No license is installed. |

title: Update license {#put-license}

text:
PUT /v1/license

Validate and install a new license string.

If you do not provide a valid license, the cluster behaves as if the license was deleted. See [Expired cluster license]() for a list of available actions and restrictions.

#### Required permissions

| Permission name |
|-----------------|
| [install_new_license]() |

title: Request {#put-request}

text:
The request must be a JSON object with a single key named "license".

#### Example HTTP request

	PUT /v1/license

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Accept | application/json | Accepted media type |

#### Request body

Include a JSON object that contains the new `license` string in the request body.

title: Response {#put-response}

text: Returns an error if the new license is not valid.

title: Status codes {#put-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | License installed successfully. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Invalid request, either bad JSON object or corrupted license was supplied. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | License violation. A response body provides more details on the specific cause. |

license: ----- LICENSE START -----\ndi+iK...KniI9\n----- LICENSE END -----\n

owner: Redis

section_id: response-get-response

license:
----- LICENSE START -----
di+iK...KniI9
----- LICENSE END -----

section_id: request-put-request


title: Logs requests

summary: Cluster event logs requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-logs) | `/v1/logs` | Get cluster events log |

title: Get cluster events log {#get-logs}

text:
GET /v1/logs

Get cluster events log.

#### Required permissions

| Permission name |
|-----------------|
| [view_logged_events]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/logs?order=desc

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| stime | ISO_8601 | Start time before which we don't want events. (optional) |
| etime | ISO_8601 | End time after which we don't want events. (optional) |
| order | string | desc/asc - get events in descending or ascending order. Defaults to asc. |
| limit | integer | Maximum number of events to return. (optional) |
| offset | integer | Skip offset events before returning first one (useful for pagination). (optional) |

title: Response {#get-response}

text:
Returns a JSON array of events.

#### Example JSON body

[code example]

#### Event object

| Field | Description |
|-------|-------------|
| time | Timestamp when event happened. |
| type | Event type. Additional fields may be available for certain event types. |
| additional fields | Additional fields may be present based on event type.|

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |

severity: INFO

old_val: test

bdb_name: test


title: Migrations requests

summary: REST API request to get the migration status of a database in the cluster when using Replica Of.

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-migrations) | `/v1/migrations/<uid>` | Get database migration status |

title: Get migration status {#get-migrations}

text:
[code example]

Gets the migration status of a database in the cluster when using Replica Of.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [view_bdb_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The database's unique ID |

title: Response {#get-response}

text:
Returns a JSON array with all data required by the migration orchestrator.

#### Example response body

[code example]

#### Status codes {#get-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Database does not exist |

code: GET /v1/migrations/<uid>

section_id: get-migration-status-get-migrations

code: GET /v1/migrations/1

section_id: request-get-request

status: string

run_id: string

replication_id: string

error_code: string

message: string


title: Configure module requests

summary: Configure module requests

title: Overview

text:
This REST API path is deprecated as of Redis Software version 7.4. Use [`PUT /v2/bdbs/<uid>`]() instead.

| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-modules-config-bdb) | `/v1/modules/config/bdb/{uid}` | Configure module |

title: Configure module {#post-modules-config-bdb}

role: configuration

text:
POST /v1/modules/config/bdb/{string: uid}

Use the module runtime configuration command (if defined) to configure new arguments for the module.

#### Required permissions

| Permission name |
|-----------------|
| [edit_bdb_module]() |

title: Request {#post-request}

text:
#### Example HTTP request

	POST /v1/modules/config/bdb/1

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

| Field | Type | Description |
|-------|------|-------------|
| modules | list of JSON objects | List of modules (module_name) and their new configuration settings (module_args) |
| module_name | `search`
`ReJSON`
`graph`
`timeseries`
`bf` | Module's name |
| module_args | string | Module command line arguments (pattern does not allow special characters &,<,>,") |

title: Response {#post-response}

text: Returns a status code. If an error occurs, the response body may include an error code and message with more details.

title: Error codes {#post-error-codes}

role: errors

text:
When errors are reported, the server may return a JSON object with `error_code` and `message` field that provide additional information. The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| db_not_exist | Database with given UID doesn't exist in cluster |
| missing_field | "module_name" or "module_args" are not defined in request |
| invalid_schema | JSON object received is not a dict object |
| param_error | "module_args" parameter was not parsed properly |
| module_not_exist | Module with given "module_name" does not exist for the database |

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, module updated on bdb. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb not found. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Module does not support runtime configuration of arguments. |

module_name: search

module_args: MINPREFIX 3 MAXEXPANSIONS 1000


title: Modules requests

summary: Redis modules requests

summary: Configure module requests

title: Configure module requests

summary: Custom, user-defined Redis module requests

title: User-defined module requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#list-modules) | `/v1/modules` | List available modules |
| [GET](#get-module) | `/v1/modules/{uid}` | Get a specific module |

title: List modules {#list-modules}

text:
[code example]

List available modules, i.e. modules stored within the CCS.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [view_cluster_modules]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#list-request}

title: Response {#list-response}

text:
Returns a JSON array of [module objects]().

#### Status codes {#list-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |

title: Get module {#get-module}

text:
[code example]

Get specific available modules, i.e. modules stored within the CCS.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [view_cluster_modules]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | 127.0.0.1:9443 | Domain name |
| Accept | \*/\* | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The module's unique ID. |

title: Response {#get-response}

text: Returns a [module object]().

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Module does not exist. |

code: GET /v1/modules

section_id: list-modules-list-modules

section_id: request-list-request

code: GET /v1/modules/{string: uid}

section_id: get-module-get-module

code: GET /v1/modules/1


title: User-defined module requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts | List custom module artifacts on a node |
| [POST](#post-user-defined-module) | /v2/modules/user-defined | Upload custom module configuration |
| [POST](#post-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts | Upload a custom module artifact to a node |
| [DELETE](#delete-user-defined-module) | /v2/modules/user-defined/<uid> | Delete a custom module configuration |
| [DELETE](#delete-local-user-defined-artifacts) | /v2/local/modules/user-defined/artifacts/<module_name>/<version> | Delete a custom module artifact from a node |

title: List custom module artifacts {#get-local-user-defined-artifacts}

text:
[code example]

Returns a list of all custom module artifacts on the local node.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [view_cluster_modules]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-local-artifacts-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | \*/\* | Accepted media type |

title: Response {#get-local-artifacts-response}

text:
Returns a JSON array of custom module artifacts.

#### Example JSON body

[code example]

title: Status codes {#get-local-artifacts-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, returns list of artifacts |

title: Upload custom module configuration {#post-user-defined-module}

text:
[code example]

Creates a module object in the cluster configuration store (CCS). After calling this endpoint, you still need to upload the module's `.zip` file, which contains the `.so` and `module.json` files, to each node by calling [`POST /v2/local/modules/user-defined/artifacts`](#post-local-user-defined-artifacts) on each node.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [manage_cluster_modules]() | admin |

title: Request {#post-user-defined-request}

text:
#### Example HTTP request

[code example]

#### Example JSON body

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

The request body is a JSON object that must contain the following fields:

| Field | Type | Description |
|-------|------|-------------|
| module_name | string | Name of the module |
| version | integer | Module version number |
| semantic_version | string | Module's semantic version |
| display_name | string | Display name for the module |
| commands | array of objects | List of commands provided by the module |
| command_line_args | string | Command line arguments for the module |
| capabilities | array of strings | List of capabilities supported by the module |
| min_redis_version | string | Minimum Redis version required |

title: Response {#post-user-defined-response}

text:
Returns a [module object]().

#### Example JSON body

[code example]

title: Status codes {#post-user-defined-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module was created in the CCS. |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | There was an issue with the module object, such as missing required fields or invalid values. |

title: Upload custom module artifact to a node {#post-local-user-defined-artifacts}

text:
[code example]

A local API to upload a custom module's artifact to the current node. You must call this API on each cluster node.

The module must be packaged as a `.zip` file containing:

- **module.json**: A metadata file with module information including:
  - `module_name`: The actual module name
  - `version`: Numeric version
  - `semantic_version`: Semantic version string (for example, "1.0.0")
  - `min_redis_version`: Minimum compatible Redis version
  - `commands`: List of commands the module provides
  - `capabilities`: List of module capabilities

- **Module binary**: The compiled `.so` file for the target platform

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [manage_cluster_modules]() | admin |

title: Request {#post-local-artifacts-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | 127.0.0.1:9443 | Domain name |
| Accept | \*/\* | Accepted media type |
| Content-Length | 865 | Length of the request body in octets |
| Expect | 100-continue | Requires particular server behaviors |
| Content-Type | multipart/form-data; boundary=------------------------4751ac3b332ace13 | Media type of request/response body |

title: Response {#post-local-artifacts-response}

text: Returns a status code to indicate upload success or failure.

title: Status codes {#post-local-artifacts-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, module artifact uploaded to local node |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Missing or bad artifact |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | There was an issue with the module object artifact, such as bad metadata |

title: Delete custom module {#delete-user-defined-module}

text:
[code example]

Delete a module object from the cluster configuration store (CCS). This REST API request does not delete the module artifact from the nodes, so you also need to call [`DELETE /v2/local/modules/user-defined/artifacts/<module_name>/<version>`](#delete-local-user-defined-artifacts) on each node.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [manage_cluster_modules]() | admin |

title: Request {#delete-user-defined-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | string | The module's unique ID |

title: Response {#delete-user-defined-response}

text: Returns a status code to indicate module deletion success or failure.

title: Status codes {#delete-user-defined-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module is deleted. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to delete a non-existing module. |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | The request is not acceptable. |

title: Delete custom module artifact from a node{#delete-local-user-defined-artifacts}

text:
[code example]

A local API to delete a custom module's artifact from the current node. You must call this API on each cluster node.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [manage_cluster_modules]() | admin |

title: Request {#delete-local-artifacts-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| module_name | string | The name of the module artifact to delete |
| version | integer | The version of the module artifact to delete |

title: Response {#delete-local-artifacts-response}

text: Returns a status code to indicate deletion success or failure.

title: Status codes {#delete-local-artifacts-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, the module artifact is deleted from the local node. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to delete a non-existing module. |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | The request is not acceptable. |

section_id: request-get-local-artifacts-request

module_name: TestModule

section_id: response-get-local-artifacts-response

code: POST /v2/modules/user-defined

section_id: request-post-user-defined-request

display_name: test module

capabilities: list of capabilities

code:
{
    "author": "author name",
    "uid": "1952fcf9a5109fb59e61b1ad4d7e2d88"
    // additional fields...
}

section_id: response-post-user-defined-response

section_id: request-post-local-artifacts-request

code: DELETE /v2/modules/user-defined/1

section_id: request-delete-user-defined-request

code: DELETE /v2/local/modules/user-defined/artifacts/{string: module_name}/{int: version}

section_id: request-delete-local-artifacts-request


title: Node master healthcheck requests

summary: REST API requests to check a node's connection to the cluster's primary node.

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-node-master-healthcheck) | `/v1/local/node/master_healthcheck` | Checks a node's connection to the primary node |

title: Get master healthcheck {#get-node-master-healthcheck}

text:
[code example]

Checks whether the current node has a valid connection to the cluster's primary node and the Cluster Configuration Store (CCS).

title: Required permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_cluster_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-response}

text:
Returns a JSON object that includes the status of the current node's connection to the cluster's primary node and the CCS.

- `active`: the current node has a valid connection.

- `inactive`: the current node doesn't have a valid connection.

#### Example JSON response body

[code example]

#### Status codes {#get-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error |

code: GET /v1/local/node/master_healthcheck

status: active


title: Node actions requests

summary: Node action requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-nodes-actions) | `/v1/nodes/actions` | Get status of all actions on all nodes|
| [GET](#get-node-actions) | `/v1/nodes/{node_uid}/actions` | Get status of all actions on a specific node |
| [GET](#get-node-action) | `/v1/nodes/{node_uid}/actions/{action}` | Get status of an action on a specific node |
| [POST](#post-node-action) | `/v1/nodes/{node_uid}/actions/{action}` | Initiate node action |
| [DELETE](#delete-node-action) | `/v1/nodes/{node_uid}/actions/{action}` | Cancel action or remove action status |

title: Get all actions {#get-all-nodes-actions}

text:
[code example]

Get the status of all currently executing, pending, or completed
actions on all nodes.

title: Permissions

role: security

text:
| Permission name | Roles |
|-----------------|-------|
| [view_status_of_all_node_actions]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

title: Response {#get-all-response}

text: Returns a list of [action objects]().

title: Status codes {#get-all-status-codes}

title: Get node actions statuses {#get-node-actions}

text:
[code example]

Get the status of all actions on a specific node.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [view_status_of_node_action]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request-all-actions}

text:
#### Example HTTP request

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| action | string | The action to check. |

title: Response {#get-response-all-actions}

text:
Returns a JSON object that includes a list of [action objects]() for the specified node.

If no actions are available, the response will include an empty array.

#### Example JSON body

[code example]

title: Error codes {#get-error-codes-all-actions}

text:
| Code | Description |
|------|-------------|
| internal_error | An internal error that cannot be mapped to a more precise error code has been encountered. |
| insufficient_resources | The cluster does not have sufficient resources to complete the required operation. |

title: Status codes {#get-status-codes-all-actions}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, response provides details about an ongoing action. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action does not exist (i.e. not currently running and no available status of last run). |

title: Get node action status {#get-node-action}

text:
[code example]

Get the status of a currently executing, queued, or completed action on a specific node.

title: Request {#get-request}

title: Response {#get-response}

text: Returns an [action object]() for the specified node.

title: Error codes {#get-error-codes}

title: Status codes {#get-status-codes}

title: Initiate node action {#post-node-action}

text:
[code example]

Initiate a node action.

The API allows only a single instance of any action type to be
invoked at the same time, and violations of this requirement will
result in a `409 CONFLICT` response.

The caller is expected to query and process the results of the
previously executed instance of the same action, which will be
removed as soon as the new one is submitted.

#### Permissions

| Permission name | Roles |
|-----------------|-------|
| [start_node_action]() | admin |

title: Request {#post-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| action | string | The name of the action required. |

Currently supported actions are:

- `remove`: Removes the node from the cluster after migrating all bound resources to other nodes. As soon as a successful remove request is received, the cluster will no longer automatically migrate resources, such as shards and endpoints, to the node even if the remove task fails at some point.

    - By default, the remove node action completes after all resources migrate off the removed node. Node removal does not wait for migrated shards' persistence files to be created on the new nodes.

        To change node removal to wait for the creation of new persistence files for all migrated shards, set `wait_for_persistence` to `true` in the request body or [update the cluster policy]() `persistent_node_removal` to `true` to change the cluster's default behavior.

        [code example]

- `maintenance_on`: Creates a snapshot of the node, migrates shards to other nodes, and prepares the node for maintenance. See [maintenance mode]() for more information.

    - As of Redis Software version 7.4.2, a new node snapshot is created only if no maintenance mode snapshots already exist or if you set `"overwrite_snapshot": true` in the request body.

        [code example]

    - If there aren't enough resources to migrate shards out of the maintained node, set `"evict_ha_replica": false` and `"evict_active_active_replica": false` in the request body to keep the replica shards in place but demote any master shards. Use these two parameters instead of `keep_slave_shards`, which is deprecated as of Redis Software version 7.4.2.

        [code example]

    - To specify databases whose shards should be evicted from the node when entering maintenance mode, set `"evict_dbs": ["List of database ID strings"]` in the request body.

        [code example]

- `maintenance_off`: Restores node to its previous state before maintenance started. See [maintenance mode]() for more information.

    - By default, it uses the latest node snapshot.

    - Use `"snapshot_name":` `"..."` in the request body to restore the state from a specific snapshot.

    - To avoid restoring shards at the node, use `"skip_shards_restore":` `true`.

- `enslave_node`: Turn node into a replica.

title: Response {#post-response}

text: The body content may provide additional action details.

title: Status codes {#delete-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Action initiated successfully. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Only a single instance of any action type can be invoked at the same time. |

title: Example requests

role: example

text:
#### cURL

[code example]

#### Python

[code example]

title: Cancel action {#delete-node-action}

text:
[code example]

Cancel a queued or executing node action, or remove the status of a
previously executed and completed action.

title: Permissions

text:
| Permission name |
|-----------------|
| [cancel_node_action]() |

title: Request {#delete-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| action | string | The name of the action to cancel. |

title: Response {#delete-response}

text:
Returns a status code.

#### Status codes {#delete-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Action will be cancelled when possible. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Action unknown or not currently running. |

code: GET /v1/nodes/actions

section_id: get-all-actions-get-all-nodes-actions

section_id: request-get-all-request

code: GET /v1/nodes/{node_uid}/actions

code: GET /v1/nodes/1/actions

section_id: request-get-request-all-actions

status: running

section_id: response-get-response-all-actions

section_id: get-node-action-status-get-node-action

code: GET /v1/nodes/1/actions/remove

section_id: initiate-node-action-post-node-action

code: POST /v1/nodes/1/actions/remove

code:
POST /v1/nodes/<node_id>/actions/remove
        {
            "wait_for_persistence": true
        }

code:
POST /v1/nodes/1/actions/maintenance_on
        {
            "overwrite_snapshot": true
        }

code:
POST /v1/nodes/1/actions/maintenance_on
        {
            "overwrite_snapshot": true,
            "evict_ha_replica": false,
            "evict_active_active_replica": false
        }

code:
POST /v1/nodes/1/actions/maintenance_on
        {
            "overwrite_snapshot": true,
            "evict_dbs": ["1", "3"]
        }

code:
$ curl -k -X POST -u "[username]:[password]" -d "{}"
            https://[host][:port]/v1/nodes/1/actions/remove

section_id: example-requests

code:
import requests
import json

url = "https://[host][port]/v1/nodes/1/actions/remove"

payload = json.dumps({})
headers = {
  'Content-Type': 'application/json',
}
auth = ("[username]", "[password]")

response = requests.request("POST", url, auth=auth, headers=headers, data=payload)

print(response.text)

section_id: cancel-action-delete-node-action

code: DELETE /v1/nodes/1/actions/remove

section_id: request-delete-request


title: Node alerts requests

summary: Node alert requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-nodes-alerts) | `/v1/nodes/alerts` | Get all alert states for all nodes |
| [GET](#get-node-alerts) | `/v1/nodes/alerts/{uid}` | Get all alert states for a node |
| [GET](#get-node-alert) | `/v1/nodes/alerts/{uid}/{alert}` | Get node alert state |

title: Get all alert states {#get-all-nodes-alerts}

text:
GET /v1/nodes/alerts

Get all alert states for all nodes.

#### Required permissions

| Permission name |
|-----------------|
| [view_all_nodes_alerts]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/nodes/alerts

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| ignore_settings | boolean | Retrieve updated alert state regardless of the cluster's alert_settings. When not present, a disabled alert will always be retrieved as disabled with a false state. (optional) |

title: Response {#get-all-response}

text:
Returns a hash of node UIDs and the [alert states]() for each node.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get node alert states {#get-node-alerts}

text:
GET /v1/nodes/alerts/{int: uid}

Get all alert states for a node.

#### Required permissions

| Permission name |
|-----------------|
| [view_node_alerts]() |

title: Request {#get-request-all-alerts}

text:
#### Example HTTP request

	GET /v1/nodes/alerts/1

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| ignore_settings | boolean | Retrieve updated alert state regardless of the cluster's alert_settings. When not present, a disabled alert will always be retrieved as disabled with a false state. (optional) |

title: Response {#get-response-all-alerts}

text:
Returns a hash of [alert objects]() and their states for a specific node.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes-all-alerts}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified node does not exist |

title: Get node alert state {#get-node-alert}

text:
GET /v1/nodes/alerts/{int: uid}/{alert}

Get a node alert state.

#### Required permissions

| Permission name |
|-----------------|
| [view_node_alerts]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/nodes/alerts/1/node_cpu_utilization

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| ignore_settings | boolean | Retrieve updated alert state regardless of the cluster's alert_settings. When not present, a disabled alert will always be retrieved as disabled with a false state. (optional) |

title: Response {#get-response}

text:
Returns an [alert object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Specified alert or node does not exist |

code:
{
    "1": {
        "node_cpu_utilization": {
            "change_time": "2014-12-22T10:42:00Z",
            "change_value": {
                "cpu_util": 2.500000000145519,
                "global_threshold": "1",
                "state": true
            },
            "enabled": true,
            "state": true,
            "severity": "WARNING"
        },
        "..."
    },
    "..."
}

section_id: response-get-all-response

code:
{
   "node_cpu_utilization": {
        "change_time": "2014-12-22T10:42:00Z",
        "change_value": {
            "cpu_util": 2.500000000145519,
            "global_threshold": "1",
            "state": true
        },
        "enabled": true,
        "state": true,
        "severity": "WARNING",
    },
    "..."
}

section_id: response-get-response-all-alerts

section_id: response-get-response


title: Check node requests

summary: Requests that run checks on a cluster node.

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-node-check) | `/v1/nodes/check/{uid}` | Runs checks on a cluster node |

title: Check node {#get-node-check}

text:
GET /v1/nodes/check/{int: uid}

Runs the following checks on a cluster node:

| Check name | Description |
|-----------|-------------|
| bootstrap_status | Verifies the local node's bootstrap process completed without errors. |
| services | Verifies all Redis Software services are running. |
| port_range | Verifies the [`ip_local_port_range`](https://www.kernel.org/doc/html/latest/networking/ip-sysctl.html) doesn't conflict with the ports Redis Software might assign to shards. |
| pidfiles | Verifies all active local shards have PID files. |
| capabilities | Verifies all binaries have the proper capability bits. |
| existing_sockets | Verifies sockets exist for all processes that require them. |
| host_settings | Verifies the following:
• Linux `overcommit_memory` setting is 1.
• `transparent_hugepage` is disabled.
• Socket maximum connections setting `somaxconn` is 1024. |
| tcp_connectivity | Verifies this node can connect to all other alive nodes. |

#### Required permissions

| Permission name |
|-----------------|
| [view_node_check]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/nodes/check/1

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The node's unique ID. |

title: Response {#get-response}

text:
Returns a JSON object with the node's check results.

When errors occur, the server returns a JSON object with `result: false` and an `error` field that provides additional information. If an error occurs during a check, the `error` field only includes a message for the first check that fails.

Possible `error` messages:

- "bootstrap request to cnm_http failed,resp_code: ...,resp_content: ..."
- "process ... is not running or not responding (...)"
- "could not communicate with 'supervisorctl': ..."
- "connectivity check failed retrieving ports for testing"

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error |


title: Node debug info requests

summary: Documents the Redis Software REST API /nodes/debuginfo requests.

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-debuginfo-all-nodes) | `/v1/nodes/debuginfo` | Get debug info from all nodes |
| [GET](#get-debuginfo-node) | `/v1/nodes/{node_uid}/debuginfo` | Get debug info from a specific node |

title: Get debug info from all nodes {#get-debuginfo-all-nodes}

text:
GET /v1/nodes/debuginfo

Downloads a tar file that contains debug info from all nodes.

#### Required permissions

| Permission name |
|-----------------|
| [view_debugging_info]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/nodes/debuginfo

title: Response {#get-all-response}

text:
Downloads the debug info in a tar file called `filename.tar.gz`. Extract the files from the tar file to access the debug info.

#### Response headers

| Key | Value | Description |
|-----|-------|-------------|
| Content-Type | application/x-gzip | Media type of request/response body |
| Content-Length | 653350 | Length of the response body in octets |
| Content-Disposition | attachment; filename=debuginfo.tar.gz | Display response in browser or download as attachment |

title: Status codes {#get-all-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success. |
| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Failed to get debug info. |

title: Get node debug info {#get-debuginfo-node}

text:
GET /v1/nodes/{int: node_uid}/debuginfo

Downloads a tar file that contains debug info from a specific node.

#### Required permissions

| Permission name |
|-----------------|
| [view_debugging_info]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/nodes/1/debuginfo

title: Response {#get-response}

title: Status codes {#get-status-codes}


title: Nodes requests

summary: Node requests

summary: Node action requests

title: Node actions requests

summary: Node alert requests

title: Node alerts requests

title: Check node requests

title: Node debug info requests

summary: Node snapshot requests

title: Node snapshot requests

summary: Node statistics requests

title: Node stats requests

summary: Requests that return a node's hostname and role.

title: Node status requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-nodes) | `/v1/nodes` | Get all cluster nodes |
| [GET](#get-node) | `/v1/nodes/{uid}` | Get a single cluster node |
| [PUT](#put-node) | `/v1/nodes/{uid}` | Update a node |

title: Get all nodes {#get-all-nodes}

text:
[code example]

Get all cluster nodes.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_all_nodes_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

title: Response {#get-all-response}

text:
Returns a JSON array of [node objects]().

#### Example JSON body

[code example]

#### Status codes {#get-all-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |

title: Get node {#get-node}

text:
[code example]

Get a single cluster node.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_node_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the node requested. |

title: Response {#get-response}

text:
Returns a [node object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Node UID does not exist |

title: Update node {#put-node}

text:
[code example]

Update a [node object]().

Currently, you can edit the following attributes:

| Field | Type/Value | Description |
|-------|------------|-------------|
| accept_servers | boolean (default: true) | The node only accepts new shards if `accept_servers` is `true` |
| addr | string | Internal IP address of node |
| external_addr | complex object | External IP addresses of node. `GET /v1/jsonschema` to retrieve the object's structure. |
| max_listeners | integer | Maximum number of listeners on the node |
| max_redis_forks | integer (default: -1) | Maximum number of background processes forked from shards that can exist on the node at any given time. Set to 0 for unlimited. Set to -1 to use cluster settings. |
| max_redis_servers | integer | Maximum number of shards on the node |
| max_slave_full_syncs | integer (default: -1) | Maximum number of simultaneous replica full syncs that can run at any given time. Set to 0 for unlimited. Set to -1 to use cluster settings. |
| rack_id | string | Rack ID where node is installed |
| recovery_path | string | Recovery files path |
| second_rack_id | string | Second rack ID where node is installed |

You can only update the `addr` attribute for offline nodes. Otherwise, the request returns an error.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [update_node]() | admin |

title: Request {#put-request}

text:
#### Example HTTP request

[code example]

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
| Content-Type | application/json | Media type of request/response body |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the updated node. |

#### Body

| Field | Type | Description |
|-------|------|-------------|
| addr | string | Internal IP address of node |
| external_addr | JSON array | External IP addresses of the node |
| recovery_path | string | Path for recovery files |
| accept_servers | boolean | If true, no shards will be created on the node |

title: Response {#put-response}

text:
If the request is successful, the body will be empty. Otherwise, it may contain a JSON object with an error code and error message.

#### Status codes {#put-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, the request has been processed. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Update request cannot be processed. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad content provided. |

#### Error codes {#put-error-codes}

| Code | Description |
|------|-------------|
| node_not_found | Node does not exist |
| node_not_offline | Attempted to change node address while it is online |
| node_already_populated | The node contains shards or endpoints, cannot disable accept_servers |
| invalid_oss_cluster_port_mapping | Cannot enable "accept_servers" since there are databases with "oss_cluster_port_mapping" that do not have a port configuration for the current node |
| node_already_has_rack_id | Attempted to change node's rack_id when it already has one |

code: GET /v1/nodes

section_id: get-all-nodes-get-all-nodes

code:
[
    {
      "uid": 1,
      "status": "active",
      "uptime": 262735,
      "total_memory": 6260334592,
      "software_version": "0.90.0-1",
      "ephemeral_storage_size": 20639797248,
      "persistent_storage_path": "/var/opt/redislabs/persist",
      "persistent_storage_size": 20639797248,
      "os_version": "Ubuntu 14.04.2 LTS",
      "ephemeral_storage_path": "/var/opt/redislabs/tmp",
      "architecture": "x86_64",
      "shard_count": 23,
      "public_addr": "",
      "cores": 4,
      "rack_id": "",
      "supported_database_versions": [
        {
          "db_type": "memcached",
          "version": "1.4.17"
        },
        {
          "db_type": "redis",
          "version": "2.6.16"
        },
        {
          "db_type": "redis",
          "version": "2.8.19"
        }
      ],
      "shard_list": [1, 3, 4],
      "addr": "10.0.3.61"
    },
    {
      "uid": 1,
      "status": "active",
      "// additional fields..."
    }
]

code: GET /v1/nodes/{int: uid}

section_id: get-node-get-node

code: GET /v1/nodes/1

section_id: request-get-request

code:
{
    "uid": 1,
    "name": "node:1",
    "// additional fields..."
}

code: PUT /v1/nodes/{int: uid}

section_id: update-node-put-node

code: PUT /v1/nodes/1

section_id: request-put-request


title: Node snapshot requests

summary: Node snapshot requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-snapshots) | `/v1/nodes/{uid}/snapshots` | Get node snapshots |
| [DELETE](#delete-snapshot) | `/v1/nodes/{uid}/snapshots/{snapshot_name}` | Delete a node snapshot |

title: Get node snapshots {#get-snapshots}

text:
[code example]

Get all cluster node snapshots of the specified node.

title: Permissions

title: Request {#get-request}

title: Response {#get-response}

text:
Returns an array of node snapshot JSON objects.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

title: Delete node snapshot {#delete-snapshot}

text:
[code example]

Delete a cluster node snapshot. Snapshots created by maintenance mode are not deleted.

title: Permissions

title: Request {#delete-request}

text:
#### Example HTTP request

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the updated node. |
| snapshot_name | string | The unique name of the snapshot to delete. |

title: Response {#delete-response}

text:
Returns a JSON object that represents the deleted node snapshot.

#### Example JSON body

[code example]

#### Status codes {#delete-status-codes}

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Node snapshot is a maintenance snapshot and cannot be deleted |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Node uid does not exist |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Snapshot name does not exist for this node uid |

code: GET /v1/nodes/{int: uid}/snapshots

section_id: get-node-snapshots-get-snapshots

code: GET /v1/nodes/1/snapshots

section_id: delete-node-snapshot-delete-snapshot

section_id: response-delete-response


title: Node stats requests

summary: Node statistics requests

summary: Most recent node statistics requests

title: Latest node stats requests

title: Overview

text:
The v1 statistics REST API endpoints are deprecated as of Redis Software version 7.22. Use the [metrics stream engine for monitoring v2]() instead for real-time monitoring and metrics collection.

| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-nodes-stats) | `/v1/nodes/stats` | Get stats for all nodes |
| [GET](#get-node-stats) | `/v1/nodes/stats/{uid}` | Get stats for a single node |

title: Get all nodes stats {#get-all-nodes-stats}

text:
[code example]

Get statistics for all nodes.

#### Required permissions

| Permission name |
|-----------------|
| [view_all_nodes_stats]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional)  |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-all-response}

text:
Returns a JSON array of [statistics]() for all nodes.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | No nodes exist |

title: Get node stats {#get-node-stats}

text:
[code example]

Get statistics for a node.

#### Required permissions

| Permission name |
|-----------------|
| [view_node_stats]() |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the node requested. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-response}

text:
Returns [statistics]() for the specified node.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Node does not exist |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Node isn't currently active |
| [503 Service Unavailable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | Node is in recovery state |

code: GET /v1/nodes/stats

section_id: get-all-nodes-stats-get-all-nodes-stats

section_id: request-get-all-request

code: GET /v1/nodes/stats/{int: uid}

section_id: get-node-stats-get-node-stats


title: Latest node stats requests

summary: Most recent node statistics requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-nodes-stats-last) | `/v1/nodes/stats/last` | Get latest stats for all nodes |
| [GET](#get-node-stats-last) | `/v1/nodes/stats/last/{uid}` | Get latest stats for a single node |

title: Get latest stats for all nodes {#get-all-nodes-stats-last}

text:
[code example]

Get latest statistics for all nodes.

#### Required permissions

| Permission name |
|-----------------|
| [view_all_nodes_stats]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week. Default: 1sec. (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601) format (optional) |

title: Response {#get-all-response}

text:
Returns most recent [statistics]() for all nodes.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get latest node stats {#get-node-stats-last}

text:
[code example]

Get the latest statistics of a node.

#### Required permissions

| Permission name |
|-----------------|
| [view_node_stats]() |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the node requested. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| interval | string | Time interval for which we want stats: 1sec/10sec/5min/15min/1hour/12hour/1week. Default: 1sec. (optional) |
| stime | ISO_8601 | Start time from which we want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)format (optional) |
| etime | ISO_8601 | End time after which we don't want the stats. Should comply with the [ISO_8601](https://en.wikipedia.org/wiki/ISO_8601)format (optional) |

title: Response {#get-response}

text:
Returns the most recent [statistics]() for the specified node.

#### Example JSON body

[code example]

title: Error codes {#get-error-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Node does not exist |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Node isn't currently active |
| [503 Service Unavailable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.4) | Mode is in recovery state |

code: GET /v1/nodes/stats/last

code: GET /v1/nodes/stats/last/{int: uid}


title: Node status requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-nodes-status) | `/v1/nodes/status` | Get the status of all nodes |
| [GET](#get-node-status) | `/v1/nodes/{uid}/status` | Get a node's status |

title: Get all node statuses {#get-all-nodes-status}

text:
GET /v1/nodes/status

Gets the status of all nodes. Includes each node's hostname and role in the cluster:

- Primary nodes return `"role": "master"`

- Replica nodes return `"role": "slave"`

#### Required permissions

| Permission name |
|-----------------|
| [view_node_info]() |

title: Request {#get-all-request}

text:
#### Example HTTP request

	GET /v1/nodes/status

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-all-response}

text:
For each node in the cluster, returns a JSON object that contains each node's hostname, role, and other status details.

If a maintenance snapshot exists due to an in-progress or improperly stopped [node maintenance]() process, the response includes a `maintenance_snapshot` field.

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get node status {#get-node-status}

text:
GET /v1/nodes/{int: uid}/status

Gets the status of a node. Includes the node's hostname and role in the cluster:

- Primary nodes return `"role": "master"`

- Replica nodes return `"role": "slave"`

#### Required permissions

| Permission name |
|-----------------|
| [view_node_info]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/nodes/1/status

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The node's unique ID. |

title: Response {#get-response}

text:
Returns a JSON object that contains the node's hostname, role, and other status details.

If a maintenance snapshot exists due to an in-progress or improperly stopped [node maintenance]() process, the response includes a `maintenance_snapshot` field.

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Node UID does not exist |

code:
{
    "1": {
        "cores": 8,
        "free_provisional_ram": 0,
        "free_ram": 3499368448,
        "hostname": "3d99db1fdf4b",
        "maintenance_snapshot": {
            "created_time": "2024-09-06 20:47:23",
            "name": "maintenance_mode_2024-09-06_20-47-23",
            "node_uid": "1"
        },
        "master_shards": [],
        "node_overbooking_depth": 0,
        "node_status": "active",
        "role": "master",
        "slave_shards": [],
        "software_version": "7.4.6-22",
        "software_version_sha": "6c37b1483b5fb6110c8055c1526aa58eec1d29d3519e92310859101419248831",
        "total_memory": 6219673600,
        "total_provisional_ram": 0
    },
    "2": {
        "hostname": "fc7a3d332458",
        "role": "slave",
        // additional fields
    },
    "3": {
        "hostname": "b87cc06c830f",
        "role": "slave",
        // additional fields
    }
}

node_status: active

role: master


title: OCSP requests

summary: OCSP requests

summary: OCSP status requests

title: OCSP status requests

summary: OCSP test requests

title: OCSP test requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-ocsp) | `/v1/ocsp` | Get OCSP configuration |
| [PUT](#put-ocsp) | `/v1/ocsp` | Update OCSP configuration |

title: Get OCSP configuration {#get-ocsp}

text:
GET /v1/ocsp

Gets the cluster's OCSP configuration.

#### Required permissions

| Permission name |
|-----------------|
| [view_ocsp_config]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/ocsp

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-response}

text:
Returns an [OCSP configuration object]().

#### Example JSON body

[code example]

title: Error codes {#get-error-codes}

text:
When errors occur, the server returns a JSON object with `error_code` and `message` fields that provide additional information. The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| ocsp_unsupported_by_capability | Not all nodes support OCSP capability |

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Feature not supported in all nodes |

title: Update OCSP configuration {#put-ocsp}

text:
PUT /v1/ocsp

Updates the cluster's OCSP configuration.

#### Required permissions

| Permission name |
|-----------------|
| [config_ocsp]() |

title: Request {#put-request}

text:
#### Example HTTP request

	PUT /v1/ocsp

#### Example JSON body

[code example]

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Request body

Include an [OCSP configuration object]() with updated fields in the request body.

title: Response {#put-response}

text: Returns the updated [OCSP configuration object]().

title: Error codes {#put-error-codes}

text:
When errors occur, the server returns a JSON object with `error_code` and `message` fields that provide additional information. The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| invalid_schema | An illegal parameter or a parameter with an illegal value |
| no_responder_url | Tried to enable OCSP with no responder URL configured |
| ocsp_unsupported_by_capability | Not all nodes support OCSP capability |

title: Status codes {#put-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, OCSP config has been set |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Feature not supported in all nodes |


title: OCSP status requests

summary: OCSP status requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-status) | `/v1/ocsp/status` | Get OCSP status |

title: Get OCSP status {#get-status}

text:
GET /v1/ocsp/status

Gets the latest cached status of the proxy certificate’s OCSP response.

#### Required permissions

| Permission name |
|-----------------|
| [view_ocsp_status]() |

title: Request {#get-request}

text:
#### Example HTTP request

	GET /v1/ocsp/status

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#get-response}

text:
Returns an [OCSP status object]().

#### Example JSON body

[code example]

title: Error codes {#get-error-codes}

text:
When errors occur, the server returns a JSON object with `error_code` and `message` fields that provide additional information. The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| ocsp_unsupported_by_capability | Not all nodes support OCSP capability |
| invalid_ocsp_response | The server returned a response that is not OCSP-compatible |

title: Status codes {#get-status-codes}

cert_status: REVOKED


title: OCSP test requests

summary: OCSP test requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-test) | `/v1/ocsp/test` | Test OCSP |

title: Test OCSP {#post-test}

text:
POST /v1/ocsp/test

Queries the OCSP server for the proxy certificate’s latest status and returns the response as JSON. It caches the response if the OCSP feature is enabled.

#### Required permissions

| Permission name |
|-----------------|
| [test_ocsp_status]() |

title: Request {#post-request}

text:
#### Example HTTP request

	POST /v1/ocsp/test

#### Request headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

title: Response {#post-response}

title: Error codes {#post-error-codes}

text:
When errors occur, the server returns a JSON object with `error_code` and `message` fields that provide additional information. The following are possible `error_code` values:

| Code | Description |
|------|-------------|
| no_responder_url | Tried to test OCSP status with no responder URL configured |
| ocsp_unsupported_by_capability | Not all nodes support OCSP capability |
| task_queued_for_too_long | OCSP polling task was in status "queued" for over 5 seconds |
| invalid_ocsp_response | The server returned a response that is not compatible with OCSP |

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success querying the OCSP server |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Feature is not supported in all nodes |
| [500 Internal Server Error](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | `responder_url` is not configured or polling task failed |

section_id: response-post-response


title: Proxy requests

summary: Proxy requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-proxies) | `/v1/proxies` | Get all proxies |
| [GET](#get-proxy) | `/v1/proxies/{uid}` | Get a proxy |
| [PUT](#put-proxy) | `/v1/proxies/{uid}` | Update a proxy |
| [PUT](#put-all-proxies) | `/v1/proxies` | Update all proxies |

title: Get all proxies {#get-all-proxies}

text:
[code example]

Get all the proxies in the cluster.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_all_proxies_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

title: Response {#get-all-response}

text:
Returns a JSON array of [proxy objects]().

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

title: Get proxy {#get-proxy}

text:
[code example]

Get a single proxy's info.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_proxy_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The proxy's unique node ID |

title: Response {#get-response}

text:
Returns a [proxy object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Proxy UID does not exist |

title: Update proxy {#put-proxy}

text:
[code example]

Updates a proxy object, notifies the proxy, and waits for acknowledgment (ACK) unless the node is dead.

Automatically restarts the proxy service if `allow_restart` is `true` and any updated parameters require a restart for the changes to take effect. For example, a restart is required if you change `threads` to a lower number.

However, if `allow_restart` is `false`, such changes only take effect after the next proxy restart.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [update_proxy]() | admin<br />user_manager |

title: Request {#put-request}

text:
#### Example HTTP request

[code example]

#### Example JSON body

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
| Content-Type | application/json | Request body media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the updated proxy. Corresponds to the node ID. |

#### Request body

Include a JSON object in the request body. The JSON object can contain the boolean field `allow_restart` and a [proxy object]() with updated fields.

title: Response {#put-response}

text: Returns a status code to indicate the success or failure of the proxy update.

title: Status codes {#put-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, the request has been processed |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad content provided |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Proxy does not exist |
| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Error while waiting for confirmation from proxy |
| [504 Gateway Timeout](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5) | Timeout while waiting for confirmation from proxy |

title: Update all proxies {#put-all-proxies}

text:
[code example]

Updates all the proxy objects, notifies the proxies, and waits for acknowledgment (ACK) unless the node is dead.

Automatically restarts the relevant proxy services if `allow_restart` is `true` and any updated parameters require a restart for the changes to take effect.

However, if `allow_restart` is `false`, such changes only take effect after the next proxy restart.

title: Permissions

title: Request {#put-all-request}

text:
#### Example HTTP request

[code example]

#### Example JSON body

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
| Content-Type | application/json | Request body media type |

#### Request body

Include a JSON object in the request body. The JSON object can contain the boolean field `allow_restart` and a [proxy object]() with updated fields.

title: Response {#put-all-response}

text: Returns a status code to indicate the success or failure of the proxy updates.

title: Status codes {#put-all-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error, the request has been processed |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad content provided |
| [500 Internal Server Error](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.1) | Error while waiting for confirmation from proxy |
| [504 Gateway Timeout](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.5) | Timeout while waiting for confirmation from proxy |

code: GET /v1/proxies

section_id: get-all-proxies-get-all-proxies

code:
[
    {
         "uid": 1,
         "client_keepintvl": 30,
         "max_worker_server_conns": 16384,
         "client_keepcnt": 6,
         "max_threads": 64,
         "ignore_bdb_cconn_output_buff_limits": false,
         "dynamic_threads_scaling": false,
         "max_worker_client_conns": 16384,
         "max_servers": 4096,
         "client_keepidle": 180,
         "duration_usage_threshold": 30,
         "max_worker_txns": 65536,
         "threads": 3,
         "max_listeners": 1024,
         "conns": 500000,
         "ignore_bdb_cconn_limit": false,
         "threads_usage_threshold": 80,
         "backlog": 1024
    },
    {
        "uid": 2,
        "threads": 3,
        // additional fields...
    }
]

code: GET /v1/proxies/{int: uid}

section_id: get-proxy-get-proxy

code: GET /v1/proxies/1

code: PUT /v1/proxies/{int: uid}

section_id: update-proxy-put-proxy

code: PUT /v1/proxies/1

code: PUT /v1/proxies

section_id: update-all-proxies-put-all-proxies

section_id: request-put-all-request


title: Redis access control list (ACL) requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-redis_acls) | `/v1/redis_acls` | Get all Redis ACLs |
| [GET](#get-redis_acl) | `/v1/redis_acls/{uid}` | Get a single Redis ACL |
| [PUT](#put-redis_acl) | `/v1/redis_acls/{uid}` | Update a Redis ACL |
| [POST](#post-redis_acl) | `/v1/redis_acls` | Create a new Redis ACL |
| [DELETE](#delete-redis_acl) | `/v1/redis_acls/{uid}` | Delete a Redis ACL |

title: Get all Redis ACLs {#get-all-redis_acls}

text:
[code example]

Get all Redis ACL objects.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_all_redis_acls_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-all-request}

title: Response {#get-all-response}

text:
Returns a JSON array of [Redis ACL objects]().

#### Example JSON body

[code example]

title: Status codes {#get-all-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support redis_acl yet. |

title: Get Redis ACL {#get-redis_acl}

text:
[code example]

Get a single Redis ACL object.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [view_redis_acl_info]() | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The object's unique ID. |

title: Response {#get-response}

text:
Returns a [Redis ACL object]().

#### Example JSON body

[code example]

title: Status codes {#get-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success. |
| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Operation is forbidden. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | redis_acl does not exist. |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support redis_acl yet. |

title: Update Redis ACL {#put-redis_acl}

text:
[code example]

Update an existing Redis ACL object.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [update_redis_acl]() | admin<br />user_manager |

title: Request {#put-request}

text:
#### Example HTTP request

[code example]

#### Example JSON body

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field   | Type | Description |
|---------|------|---------------|
| dry_run |  | Validate the updated [Redis ACL object]() but don't apply the update. |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The Redis ACL's unique ID. |

#### Request body

Include a [Redis ACL object]() with updated fields in the request body.

title: Response {#put-response}

text:
Returns the updated [Redis ACL object]().

#### Example JSON body

[code example]

title: Error codes {#put-error-codes}

text:
| Code | Description |
|------|-------------|
| unsupported_resource | The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version.|
| name_already_exists | An object of the same type and name exists|
| invalid_param | A parameter has an illegal value|

title: Status codes {#put-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, redis_acl was updated. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to change a non-existent redis_acl. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Cannot change a read-only object |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support redis_acl yet. |

title: Create Redis ACL {#post-redis_acl}

text:
[code example]

Create a new Redis ACL object.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [create_redis_acl]() | admin<br />user_manager |

title: Request {#post-request}

text:
#### Example HTTP request

[code example]

#### Example JSON body

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### Query parameters

| Field   | Type | Description |
|---------|------|---------------|
| dry_run |  | Validate the new [Redis ACL object]() but don't apply the update. |

#### Request body

Include a [Redis ACL object]() in the request body.

title: Response {#post-response}

text:
Returns the newly created [Redis ACL object]().

#### Example JSON body

[code example]

title: Error codes {#post-error-codes}

text:
Possible `error_code` values:

| Code | Description |
|------|-------------|
| unsupported_resource | The cluster is not yet able to handle this resource type. This could happen in a partially upgraded cluster, where some of the nodes are still on a previous version. |
| name_already_exists | An object of the same type and name exists |
| missing_field | A needed field is missing |
| invalid_param | A parameter has an illegal value |

title: Status codes {#post-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, redis_acl is created. |
| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Bad or missing configuration parameters. |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support redis_acl yet. |

title: Examples

text:
#### cURL

[code example]

#### Python

[code example]

title: Delete Redis ACL {#delete-redis_acl}

text:
[code example]

Delete a Redis ACL object.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [delete_redis_acl]() | admin<br />user_manager |

title: Request {#delete-request}

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The redis_acl unique ID. |

title: Response {#delete-response}

text: Returns a status code that indicates the Redis ACL deletion success or failure.

title: Status codes {#delete-status-codes}

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | Success, the redis_acl is deleted. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | The request is not acceptable. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Cannot delete a read-only object |
| [501 Not Implemented](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.5.2) | Cluster doesn't support redis_acl yet. |

code: GET /v1/redis_acls

section_id: get-all-redis-acls-get-all-redis-acls

Read Only

acl: +@read ~*

Not Dangerous

acl: +@all -@dangerous ~*

section_id: response-get-all-response

code: GET /v1/redis_acls/{int: uid}

section_id: get-redis-acl-get-redis-acl

code: GET /v1/redis_acls/1

section_id: response-get-response

code: PUT /v1/redis_acls/{int: uid}

section_id: update-redis-acl-put-redis-acl

code: PUT /v1/redis_acls/17

acl: ~* +@geo -@dangerous

section_id: response-put-response

code: POST /v1/redis_acls

section_id: create-redis-acl-post-redis-acl

section_id: request-post-request

code:
curl -k -u "[username]:[password]" -X POST \
     -H 'Content-Type: application/json' \
     -d '{ "name": "Geo", "acl": "~* +@geo" }' \
     https://[host][:port]/v1/redis_acls

section_id: examples

code:
import requests
import json

url = "https://[host][:port]/v1/redis_acls"

headers = {
  'Content-Type': 'application/json'
}

payload = json.dumps({
    "name": "Geo",
    "acl": "~* +@geo"
})
auth=("[username]", "[password]")

response = requests.request("POST", url,
           auth=auth, headers=headers, payload=payload, verify=False)

print(response.text)

code: DELETE /v1/redis_acls/{int: uid}

section_id: delete-redis-acl-delete-redis-acl

code: DELETE /v1/redis_acls/1

section_id: request-delete-request