title: State machine object

summary: An object that represents a state machine.

title: Content

text:
A state machine object tracks the status of database actions.

A state machine contains the following attributes:

| Name        | Type/Value | Description |
|-------------|------------|-------------|
| action_uid  | string     | A globally unique identifier of the action |
| object_name | string     | Name of the object being manipulated by the state machine |
| status      | pending    | Requested state machine has not started |
|             | active     | State machine is currently running |
|             | completed  | Operation complete |
|             | failed     | Operation or state machine failed |
| name        | string     | Name of the running (or failed) state machine |
| state       | string     | Current state within the state machine, when known |
| error       | string     | A descriptive error string for failed state machine, when known |


title: Cluster metrics

summary: Documents the cluster metrics used with Redis Software REST API calls.

page_type: content

title: Content

role: content

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.

| Metric name | Type | Description |
|-------------|------|-------------|
| available_flash | float | Sum of available flash in all nodes (bytes) |
| available_memory | float | Sum of available memory in all nodes (bytes) |
| avg_latency | float | Average latency of requests handled by all cluster endpoints (micro-sec); returned only when there is traffic |
| bigstore_free | float | Sum of free space of backend flash (used by flash DB's BigRedis) on all cluster nodes (bytes); only returned when BigRedis is enabled |
| bigstore_iops | float | Rate of I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) in the cluster (ops/sec); returned only when BigRedis is enabled |
| bigstore_kv_ops | float | Rate of value read/write operations against back-end flash for all shards which are part of a flash based DB (BigRedis) in cluster (ops/sec); only returned when BigRedis is enabled |
| bigstore_throughput | float | Throughput I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) in the cluster (bytes/sec); only returned when BigRedis is enabled |
| conns | float | Total number of clients connected to all cluster endpoints |
| cpu_idle | float | CPU idle time portion, the value is weighted between all nodes based on number of cores in each node (0-1, multiply by 100 to get percent) |
| cpu_system | float | CPU time portion spent in kernel on the cluster, the value is weighted between all nodes based on number of cores in each node (0-1, multiply by 100 to get percent) |
| cpu_user | float | CPU time portion spent by users-pace processes on the cluster. The value is weighted between all nodes based on number of cores in each node (0-1, multiply by 100 to get percent). |
| egress_bytes | float | Sum of rate of outgoing network traffic on all cluster nodes (bytes/sec) |
| ephemeral_storage_avail | float | Sum of disk space available to Redis Software processes on configured ephemeral disk on all cluster nodes (bytes) |
| ephemeral_storage_free | float | Sum of free disk space on configured ephemeral disk on all cluster nodes (bytes) |
| free_memory | float | Sum of free memory in all cluster nodes (bytes) |
| ingress_bytes | float | Sum of rate of incoming network traffic on all cluster nodes (bytes/sec) |
| persistent_storage_avail | float | Sum of disk space available to Redis Software processes on configured persistent disk on all cluster nodes (bytes) |
| persistent_storage_free | float | Sum of free disk space on configured persistent disk on all cluster nodes (bytes) |
| provisional_flash | float | Sum of provisional flash in all nodes (bytes) |
| provisional_memory | float | Sum of provisional memory in all nodes (bytes) |
| total_req | float | Request rate handled by all endpoints on the cluster (ops/sec) |


title: DB metrics

summary: Documents the DB metrics used with Redis Software REST API calls.

title: Content

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.

| Metric name | Type | Description |
|-------------|------|-------------|
| avg_latency | float | Average latency of operations on the DB (microseconds). Only returned when there is traffic. |
| avg_other_latency | float | Average latency of other (non read/write) operations (microseconds). Only returned when there is traffic. |
| avg_read_latency | float | Average latency of read operations (microseconds). Only returned when there is traffic. |
| avg_write_latency | float | Average latency of write operations (microseconds). Only returned when there is traffic. |
| big_del_flash | float | Rate of key deletes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_del_ram | float | Rate of key deletes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. |
| big_fetch_flash | float | Rate of key reads/updates for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_fetch_ram | float | Rate of key reads/updates for keys in RAM (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_io_ratio_flash | float | Rate of key operations on flash. Can be used to compute the ratio of I/O operations (key access/sec). Only returned when BigRedis is enabled. |
| big_io_ratio_redis | float | Rate of Redis operations on keys. Can be used to compute the ratio of I/O operations (key access/sec). Only returned when BigRedis is enabled. |
| big_write_flash | float | Rate of key writes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_write_ram | float | Rate of key writes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. |
| bigstore_io_dels | float | Rate of key deletions from flash (key access/sec). Only returned when BigRedis is enabled. |
| bigstore_io_read_bytes | float | Throughput of I/O read operations against backend flash |for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. |
| bigstore_io_reads | float | Rate of key reads from flash (key access/sec). Only returned when BigRedis is enabled. |
| bigstore_io_write_bytes | float | Throughput of I/O write operations against backend flash |for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. |
| bigstore_io_writes | float | Rate of key writes from flash (key access/sec). Only returned when BigRedis is enabled. |
| bigstore_iops | float | Rate of I/O operations against backend flash for all shards of the DB (BigRedis) (ops/sec). Only returned when BigRedis is enabled. |
| bigstore_kv_ops | float | Rate of value read/write/del operations against backend flash for all shards of the DB (BigRedis) (key access/sec). Only returned when BigRedis is enabled |
| bigstore_objs_flash | float | Value count on flash (BigRedis). Only returned when BigRedis is enabled. |
| bigstore_objs_ram | float | Value count in RAM (BigRedis). Only returned when BigRedis is enabled. |
| bigstore_throughput | float | Throughput of I/O operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. |
| conns | float | Number of client connections to the DB’s endpoints |
| disk_frag_ratio | float | Flash fragmentation ratio (used/required). Only returned when BigRedis is enabled. |
| egress_bytes | float | Rate of outgoing network traffic to the DB’s endpoint (bytes/sec) |
| evicted_objects | float | Rate of key evictions from DB (evictions/sec) |
| expired_objects | float | Rate keys expired in DB (expirations/sec) |
| fork_cpu_system | float | % cores utilization in system mode for all Redis shard fork child processes of this database |
| fork_cpu_user | float | % cores utilization in user mode for all Redis shard fork child processes of this database |
| ingress_bytes | float | Rate of incoming network traffic to the DB’s endpoint (bytes/sec) |
| instantaneous_ops_per_sec | float | Request rate handled by all shards of the DB (ops/sec) |
| last_req_time | date, ISO_8601 format | Last request time received to the DB (ISO format 2015-07-05T22:16:18Z). Returns 1/1/1970 when unavailable. |
| last_res_time | date, ISO_8601 format | Last response time received from DB (ISO format 2015-07-05T22:16:18Z). Returns 1/1/1970 when unavailable. |
| main_thread_cpu_system | float | % cores utilization in system mode for all Redis shard main threads of this database |
| main_thread_cpu_user | float | % cores utilization in user mode for all Redis shard main threads of this database |
| mem_frag_ratio | float | RAM fragmentation ratio (RSS/allocated RAM) |
| mem_not_counted_for_evict | float | Portion of used_memory (in bytes) not counted for eviction and OOM errors |
| mem_size_lua | float | Redis Lua scripting heap size (bytes) |
| monitor_sessions_count | float | Number of client connected in monitor mode to the DB |
| no_of_expires | float | Number of volatile keys in the DB |
| no_of_keys | float | Number of keys in the DB |
| other_req | float | Rate of other (non read/write) requests on DB (ops/sec) |
| other_res | float | Rate of other (non read/write) responses on DB (ops/sec) |
| pubsub_channels | float | Count the pub/sub channels with subscribed clients |
| pubsub_patterns | float | Count the pub/sub patterns with subscribed clients |
| ram_overhead | float | Non values RAM overhead (BigRedis) (bytes). Only returned when BigRedis is enabled. |
| read_hits | float | Rate of read operations accessing an existing key (ops/sec) |
| read_misses | float | Rate of read operations accessing a nonexistent key (ops/sec) |
| read_req | float | Rate of read requests on DB (ops/sec) |
| read_res | float | Rate of read responses on DB (ops/sec) |
| shard_cpu_system | float | % cores utilization in system mode for all Redis shard processes of this database |
| shard_cpu_user | float | % cores utilization in user mode for the Redis shard process |
| total_connections_received | float | Rate of new client connections to the DB (connections/sec) |
| total_req | float | Rate of all requests on DB (ops/sec) |
| total_res | float | Rate of all responses on DB (ops/sec) |
| used_bigstore | float | Flash used by DB (BigRedis) (bytes). Only returned when BigRedis is enabled. |
| used_memory | float | Memory used by DB (in BigRedis this includes flash) (bytes) |
| used_ram | float | RAM used by DB (BigRedis) (bytes). Only returned when BigRedis is enabled. |
| write_hits | float | Rate of write operations accessing an existing key (ops/sec) |
| write_misses | float | Rate of write operations accessing a nonexistent key (ops/sec) |
| write_req | float | Rate of write requests on DB (ops/sec) |
| write_res | float | Rate of write responses on DB (ops/sec) |


title: Statistics

summary: An object that contains metrics for clusters, databases, nodes, or shards

title: Cluster metrics

title: DB metrics

summary: Documents the node metrics used with Redis Software REST API calls.

title: Node metrics

summary: Documents the shard metrics used with Redis Software REST API calls.

title: Shard metrics

title: Overview

role: 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.

title: Statistics overview

text:
Clusters, databases, nodes, and shards collect various statistics at regular time intervals. View the statistics for these objects using `GET stats` requests to their respective endpoints:
- [Cluster stats]()
- [Database stats]()
- [Node stats]()
- [Shard stats]()

View endpoint stats using `GET` requests, see:
- [Endpoint stats]()

title: Response object

role: returns

text:
Statistics returned from API requests always contain the following fields:
- `interval`: a string that represents the statistics time interval. Valid values include:
    - 1sec
    - 10sec
    - 5min
    - 15min
    - 1hour
    - 12hour
    - 1week
- `stime`: a timestamp that represents the beginning of the interval, in the format "2015-05-27T12:00:00Z"
- `etime`: a timestamp that represents the end of the interval, in the format "2015-05-27T12:00:00Z"

The statistics returned by the API also contain fields that represent the values of different metrics for an object during the specified time interval.

More details about the metrics relevant to each object:
- [Cluster metrics]()
- [DB metrics]()
- [Node metrics]()
- [Shard metrics]()

Certain statistics are not documented because they are for internal use only and should be ignored. Some statistics will only appear in API responses when they are relevant.

title: Optional URL parameters

role: parameters

text:
There are several optional URL parameters you can pass to the various `GET stats` requests to filter the returned statistics.

- `stime`: limit the start of the time range of the returned statistics
- `etime`: limit the end of the time range of the returned statistics
- `metrics`: only return the statistics for the specified metrics (comma-separated list)

title: Maximum number of samples per interval

text:
The system retains a maximum number of most recent samples for each interval.

| Interval | Max samples |
|----------|-------------|
| 1sec     | 10 |
| 10sec    | 30 |
| 5min     | 12 |
| 15min    | 96 |
| 1hour    | 168 |
| 12hour   | 62 |
| 1week    | 53 |

The actual number of samples returned by a `GET stats` request depends on how many samples are available and any filters applied by the optional URL parameters. For example, newly created objects (clusters, nodes, databases, or shards) or a narrow time filter range will return fewer samples.

To reduce load generated by stats collection, relatively inactive databases or shards (less than 5 ops/sec) do not collect 1sec stats at one second intervals. Instead, they collect 1sec stats every 2-5 seconds but still retain the same maximum number of samples.


title: Node metrics

title: Content

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.

| Metric name | Type | Description |
|-------------|------|-------------|
| available_flash | float | Available flash on the node (bytes) |
| available_memory | float | Available RAM on the node (bytes) |
| avg_latency | float | Average latency of requests handled by endpoints on the node (micro-sec); returned only when there is traffic |
| bigstore_free | float | Free space of backend flash (used by flash DB's BigRedis) (bytes); returned only when BigRedis is enabled |
| bigstore_iops | float | Rate of I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) on the node (ops/sec); returned only when BigRedis is enabled |
| bigstore_kv_ops | float | Rate of value read/write operations against backend flash for all shards which are part of a flash-based DB (BigRedis) on the node (ops/sec); returned only when BigRedis is enabled |
| bigstore_throughput | float | Throughput of I/O operations against backend flash for all shards which are part of a flash-based DB (BigRedis) on the node (bytes/sec); returned only when BigRedis is enabled |
| conns | float | Number of clients connected to endpoints on the node |
| cpu_idle | float | CPU idle time portion (0-1, multiply by 100 to get percent) |
| cpu_system | float | CPU time portion spent in kernel (0-1, multiply by 100 to get percent) |
| cpu_user | float | CPU time portion spent by users-pace processes (0-1, multiply by 100 to get percent) |
| cur_aof_rewrites | float | Number of current AOF rewrites by shards on this node |
| egress_bytes | float | Rate of outgoing network traffic to the node (bytes/sec) |
| ephemeral_storage_avail | float | Disk space available to Redis Software processes on configured ephemeral disk (bytes) |
| ephemeral_storage_free | float | Free disk space on configured ephemeral disk (bytes) |
| free_memory | float | Free memory on the node (bytes) |
| ingress_bytes | float | Rate of incoming network traffic to the node (bytes/sec) |
| persistent_storage_avail | float | Disk space available to Redis Software processes on configured persistent disk (bytes) |
| persistent_storage_free | float | Free disk space on configured persistent disk (bytes) |
| provisional_flash | float | Amount of flash available for new shards on this node, taking into account overbooking, max Redis servers, reserved flash, and provision and migration thresholds (bytes) |
| provisional_memory | float | Amount of RAM available for new shards on this node, taking into account overbooking, max Redis servers, reserved memory, and provision and migration thresholds (bytes) |
| total_req | float | Request rate handled by endpoints on the node (ops/sec) |


title: Shard metrics

title: Content

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.

| Metric name | Type | Description |
|-------------|------|-------------|
| aof_rewrite_inprog | float | The number of simultaneous AOF rewrites that are in progress |
| avg_ttl | float | Estimated average time to live of a random key (msec) |
| big_del_flash | float | Rate of key deletes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_del_ram | float | Rate of key deletes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. |
| big_fetch_flash | float | Rate of key reads/updates for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_fetch_ram | float | Rate of key reads/updates for keys in RAM (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_io_ratio_flash | float | Rate of key operations on flash. Can be used to compute the ratio of I/O operations (key access/sec). Only returned when BigRedis is enabled. |
| big_io_ratio_redis | float | Rate of Redis operations on keys. Can be used to compute the ratio of I/O operations) (key access/sec). Only returned when BigRedis is enabled. |
| big_write_flash | float | Rate of key writes for keys on flash (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| big_write_ram | float | Rate of key writes for keys in RAM (BigRedis) (key access/sec); this includes write misses (new keys created). Only returned when BigRedis is enabled. |
| bigstore_io_dels | float | Rate of key deletions from flash (key access/sec). Only returned when BigRedis is enabled. |
| bigstore_io_read_bytes | float | Throughput of I/O read operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. |
| bigstore_io_reads | float | Rate of key reads from flash (key access/sec). Only returned when BigRedis is enabled. |
| bigstore_io_write_bytes | float | Throughput of I/O write operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. |
| bigstore_io_writes | float | Rate of key writes from flash (key access/sec). Only returned when BigRedis is enabled. |
| bigstore_iops | float | Rate of I/O operations against backend flash for all shards of the DB (BigRedis) (ops/sec). Only returned when BigRedis is enabled. |
| bigstore_kv_ops | float | Rate of value read/write/del operations against backend flash for all shards of the DB (BigRedis) (key access/sec). Only returned when BigRedis is enabled. |
| bigstore_objs_flash | float | Key count on flash (BigRedis). Only returned when BigRedis is enabled. |
| bigstore_objs_ram | float | Key count in RAM (BigRedis). Only returned when BigRedis is enabled. |
| bigstore_throughput | float | Throughput of I/O operations against backend flash for all shards of the DB (BigRedis) (bytes/sec). Only returned when BigRedis is enabled. |
| blocked_clients | float | Count the clients waiting on a blocking call |
| connected_clients | float | Number of client connections to the specific shard |
| disk_frag_ratio | float | Flash fragmentation ratio (used/required). Only returned when BigRedis is enabled. |
| evicted_objects | float | Rate of key evictions from DB (evictions/sec) |
| expired_objects | float | Rate keys expired in DB (expirations/sec) |
| fork_cpu_system | float | % cores utilization in system mode for the Redis shard fork child process |
| fork_cpu_user | float | % cores utilization in user mode for the Redis shard fork child process |
| last_save_time | float | Time of the last RDB save |
| main_thread_cpu_system | float | % cores utilization in system mode for the Redis shard main thread |
| main_thread_cpu_user | float | % cores utilization in user mode for the Redis shard main thread |
| mem_frag_ratio | float | RAM fragmentation ratio (RSS/allocated RAM) |
| mem_not_counted_for_evict | float | Portion of used_memory (in bytes) not counted for eviction and OOM errors |
| mem_size_lua | float | Redis Lua scripting heap size (bytes) |
| no_of_expires | float | Number of volatile keys on the shard |
| no_of_keys | float | Number of keys in DB |
| pubsub_channels | float | Count the pub/sub channels with subscribed clients |
| pubsub_patterns | float | Count the pub/sub patterns with subscribed clients |
| rdb_changes_since_last_save | float | Count changes since last RDB save |
| read_hits | float | Rate of read operations accessing an existing key (ops/sec) |
| read_misses | float | Rate of read operations accessing a nonexistent key (ops/sec) |
| shard_cpu_system | float | % cores utilization in system mode for the Redis shard process |
| shard_cpu_user | float | % cores utilization in user mode for the Redis shard process |
| total_req | float | Rate of operations on DB (ops/sec) |
| used_memory | float | Memory used by shard (in BigRedis this includes flash) (bytes) |
| used_memory_peak | float | The largest amount of memory used by this shard (bytes) |
| used_memory_rss | float | Resident set size of this shard (bytes) |
| write_hits | float | Rate of write operations accessing an existing key (ops/sec) |
| write_misses | float | Rate of write operations accessing a nonexistent key (ops/sec) |


title: Suffix object

summary: An object that represents a DNS suffix

title: Content

text:
An API object that represents a DNS suffix in the cluster.

| Name | Type/Value | Description |
|------|------------|-------------|
| default | boolean | Suffix is the default suffix for the cluster (read-only) |
| internal | boolean | Does the suffix point to internal IP addresses (read-only) |
| mdns | boolean | Support for multicast DNS (read-only) |
| name | string | Unique suffix name that represents its zone (read-only) |
| slaves | array of strings | Frontend DNS servers to be updated by this suffix |
| use_aaaa_ns | boolean | Suffix uses AAAA NS entries (read-only) |


title: User object

summary: An API object that represents a Redis Software user

title: Content

text:
| Name | Type/Value | Description |
|------|------------|-------------|
| uid | integer | User's unique ID |
| account_id | integer | SM account ID |
| action_uid | string | Action UID. If it exists, progress can be tracked by the `GET /actions/{uid}` API request (read-only) |
| auth_method | **'regular'**
'certificate'
'entraid'
'sso' | User's authentication method |
| bdbs_email_alerts | complex object | UIDs of databases that user will receive alerts for |
| certificate_subject_line | string | The certificate’s subject line as defined by RFC2253. Used for certificate-based authentication users only. |
| cluster_email_alerts | boolean | Activate cluster email alerts for a user |
| email | string | User's email (pattern matching only ASCII characters) |
| email_alerts | boolean (default: true) | Activate email alerts for a user |
| last_login | integer | UNIX timestamp of the user's last login time. This denotes the last time an authentication with the user's credentials was successful. (read-only) |
| name | string | User's name (pattern does not allow non-ASCII and special characters &,\<,>,") |
| password | string | User's password. If `password_hash_method` is set to `1`, the password should be hashed using SHA-256. The format before hashing is `username:clustername:password`. |
| password_hash_method | '1' | Used when password is passed pre-hashed to specify the hashing method |
| password_issue_date | string | The date in which the password was set (read-only) |
| role | 'admin'
'cluster_member'
'cluster_viewer'
'db_member'
 **'db_viewer'**
'user_manager'
'none' | User's [role]() |
| role_uids | array of integers | UIDs of user's roles for role-based access control |
| status | 'active'
'locked'
'password_expired' | User sign-in status (read-only)
**active**: able to sign in
**locked**: unable to sign in
**password_expired**: unable to sign in because the password expired |


title: Permissions

summary: Documents the permissions used with Redis Software REST API calls.

title: Overview

text:
Some Redis Software [REST API requests]() may require the user to have specific permissions.

Administrators can assign a predefined role to a user with the [Cluster Manager UI]() or a [<nobr>`PUT /v1/users/{uid}`</nobr> API request]() to grant necessary permissions to them.

title: Roles

text:
Each user in the cluster has an assigned cluster management role, which defines the permissions granted to the user.

Available management roles include:

- **none**: No REST API permissions.
- **[db_viewer](#db-viewer-role)**: Can view database info.
- **[db_member](#db-member-role)**: Can create or modify databases and view their info.
- **[cluster_viewer](#cluster-viewer-role)**: Can view cluster and database info.
- **[cluster_member](#cluster-member-role)**: Can modify the cluster and databases and view their info.
- **[user_manager](#user-manager-role)**: Can modify users and view their info.
- **[admin](#admin-role)**: Can view and modify all elements of the cluster.

title: Permissions list for each role

role: security

text:
| Role | Permissions |
|------|-------------|
| none | No permissions |
| admin | [add_cluster_module](#add_cluster_module), [cancel_cluster_action](#cancel_cluster_action), [cancel_node_action](#cancel_node_action), [config_ldap](#config_ldap), [config_ocsp](#config_ocsp), [config_sso](#config_sso), [create_bdb](#create_bdb), [create_crdb](#create_crdb), [create_ldap_mapping](#create_ldap_mapping), [create_new_user](#create_new_user), [create_redis_acl](#create_redis_acl), [create_role](#create_role), [delete_bdb](#delete_bdb), [delete_cluster_module](#delete_cluster_module), [delete_crdb](#delete_crdb), [delete_ldap_mapping](#delete_ldap_mapping), [delete_redis_acl](#delete_redis_acl), [delete_role](#delete_role), [delete_user](#delete_user), [edit_bdb_module](#edit_bdb_module), [failover_shard](#failover_shard), [flush_crdb](#flush_crdb), [install_new_license](#install_new_license), [manage_cluster_modules](#manage_cluster_modules), [migrate_shard](#migrate_shard), [purge_instance](#purge_instance), [reset_bdb_current_backup_status](#reset_bdb_current_backup_status), [reset_bdb_current_export_status](#reset_bdb_current_export_status), [reset_bdb_current_import_status](#reset_bdb_current_import_status), [start_bdb_export](#start_bdb_export), [start_bdb_import](#start_bdb_import), [start_bdb_recovery](#start_bdb_recovery), [start_cluster_action](#start_cluster_action), [start_node_action](#start_node_action), [test_ocsp_status](#test_ocsp_status), [update_bdb](#update_bdb), [update_bdb_alerts](#update_bdb_alerts), [update_bdb_with_action](#update_bdb_with_action), [update_cluster](#update_cluster), [update_crdb](#update_crdb), [update_ldap_mapping](#update_ldap_mapping), [update_node](#update_node), [update_proxy](#update_proxy), [update_redis_acl](#update_redis_acl), [update_role](#update_role), [update_user](#update_user), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_ldap_mappings_info](#view_all_ldap_mappings_info), [view_all_metrics](#view_all_metrics), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_all_users_info](#view_all_users_info), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_keys](#view_cluster_keys), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_debugging_info](#view_debugging_info), [view_endpoint_stats](#view_endpoint_stats), [view_ldap_config](#view_ldap_config), [view_ldap_mapping_info](#view_ldap_mapping_info), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_ocsp_config](#view_ocsp_config), [view_ocsp_status](#view_ocsp_status), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_sso](#view_sso), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action), [view_user_info](#view_user_info) |
| cluster_member | [create_bdb](#create_bdb), [create_crdb](#create_crdb), [delete_bdb](#delete_bdb), [delete_crdb](#delete_crdb), [edit_bdb_module](#edit_bdb_module), [failover_shard](#failover_shard), [flush_crdb](#flush_crdb), [migrate_shard](#migrate_shard), [purge_instance](#purge_instance), [reset_bdb_current_backup_status](#reset_bdb_current_backup_status), [reset_bdb_current_export_status](#reset_bdb_current_export_status), [reset_bdb_current_import_status](#reset_bdb_current_import_status), [start_bdb_export](#start_bdb_export), [start_bdb_import](#start_bdb_import), [start_bdb_recovery](#start_bdb_recovery), [update_bdb](#update_bdb), [update_bdb_alerts](#update_bdb_alerts), [update_bdb_with_action](#update_bdb_with_action), [update_crdb](#update_crdb), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_metrics](#view_all_metrics), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_keys](#view_cluster_keys), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_debugging_info](#view_debugging_info), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_sso](#view_sso), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) |
| cluster_viewer | [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_metrics](#view_all_metrics), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_sso](#view_sso), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) |
| db_member | [create_bdb](#create_bdb), [create_crdb](#create_crdb), [delete_bdb](#delete_bdb), [delete_crdb](#delete_crdb), [edit_bdb_module](#edit_bdb_module), [failover_shard](#failover_shard), [flush_crdb](#flush_crdb), [migrate_shard](#migrate_shard), [purge_instance](#purge_instance), [reset_bdb_current_backup_status](#reset_bdb_current_backup_status), [reset_bdb_current_export_status](#reset_bdb_current_export_status), [reset_bdb_current_import_status](#reset_bdb_current_import_status), [start_bdb_export](#start_bdb_export), [start_bdb_import](#start_bdb_import), [start_bdb_recovery](#start_bdb_recovery), [update_bdb](#update_bdb), [update_bdb_alerts](#update_bdb_alerts), [update_bdb_with_action](#update_bdb_with_action), [update_crdb](#update_crdb), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_debugging_info](#view_debugging_info), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_sso](#view_sso), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) |
| db_viewer | [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_nodes_alerts](#view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_recovery_plan](#view_bdb_recovery_plan), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_endpoint_stats](#view_endpoint_stats), [view_license](#view_license), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_sso](#view_sso), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action) |
| user_manager | [config_ldap](#config_ldap), [create_ldap_mapping](#create_ldap_mapping), [create_new_user](#create_new_user), [create_role](#create_role), [create_redis_acl](#create_redis_acl), [delete_ldap_mapping](#delete_ldap_mapping), [delete_redis_acl](#delete_redis_acl), [delete_role](#delete_role), [delete_user](#delete_user), [install_new_license](#install_new_license), [update_ldap_mapping](#update_ldap_mapping), [update_proxy](#update_proxy), [update_role](#update_role), [update_redis_acl](#update_redis_acl), [update_user](#update_user), [view_all_bdb_stats](#view_all_bdb_stats), [view_all_bdbs_alerts](#view_all_bdbs_alerts), [view_all_bdbs_info](#view_all_bdbs_info), [view_all_ldap_mappings_info](#view_all_ldap_mappings_info), [view_all_nodes_alerts](view_all_nodes_alerts), [view_all_nodes_checks](#view_all_nodes_checks), [view_all_nodes_info](#view_all_nodes_info), [view_all_nodes_stats](#view_all_nodes_stats), [view_all_proxies_info](#view_all_proxies_info), [view_all_redis_acls_info](#view_all_redis_acls_info), [view_all_roles_info](#view_all_roles_info), [view_all_shard_stats](#view_all_shard_stats), [view_all_users_info](#view_all_users_info), [view_bdb_alerts](#view_bdb_alerts), [view_bdb_info](#view_bdb_info), [view_bdb_stats](#view_bdb_stats), [view_cluster_alerts](#view_cluster_alerts), [view_cluster_info](#view_cluster_info), [view_cluster_keys](#view_cluster_keys), [view_cluster_modules](#view_cluster_modules), [view_cluster_stats](#view_cluster_stats), [view_crdb](#view_crdb), [view_crdb_list](#view_crdb_list), [view_crdb_task](#view_crdb_task), [view_crdb_task_list](#view_crdb_task_list), [view_endpoint_stats](#view_endpoint_stats), [view_ldap_config](#view_ldap_config), [view_ldap_mapping_info](#view_ldap_mapping_info), [view_license](#view_license), [view_logged_events](#view_logged_events), [view_node_alerts](#view_node_alerts), [view_node_check](#view_node_check), [view_node_info](#view_node_info), [view_node_stats](#view_node_stats), [view_proxy_info](#view_proxy_info), [view_redis_acl_info](#view_redis_acl_info), [view_redis_pass](#view_redis_pass), [view_role_info](#view_role_info), [view_shard_stats](#view_shard_stats), [view_sso](#view_sso), [view_status_of_all_node_actions](#view_status_of_all_node_actions), [view_status_of_cluster_action](#view_status_of_cluster_action), [view_status_of_node_action](#view_status_of_node_action), [view_user_info](#view_user_info)
 |

title: Roles list per permission

text:
| Permission | Roles |
|------------|-------|
| add_cluster_module| admin |
| cancel_cluster_action | admin |
| cancel_node_action | admin |
| config_ldap | admin
user_manager |
| config_ocsp | admin |
| config_sso | admin |
| create_bdb | admin
cluster_member
db_member |
| create_crdb | admin
cluster_member
db_member |
| create_ldap_mapping | admin
user_manager |
| create_new_user | admin
user_manager |
| create_redis_acl | admin
user_manager |
| create_role | admin
user_manager |
| delete_bdb | admin
cluster_member
db_member |
| delete_cluster_module | admin |
| delete_crdb | admin
cluster_member
db_member |
| delete_ldap_mapping | admin
user_manager |
| delete_redis_acl | admin
user_manager |
| delete_role | admin
user_manager |
| delete_user | admin
user_manager |
| edit_bdb_module | admin
cluster_member
db_member |
| failover_shard | admin
cluster_member
db_member |
| flush_crdb | admin
cluster_member
db_member |
| install_new_license | admin
user_manager |
| manage_cluster_modules | admin |
| migrate_shard | admin
cluster_member
db_member |
| purge_instance | admin
cluster_member
db_member |
| reset_bdb_current_backup_status | admin
cluster_member
db_member |
| reset_bdb_current_export_status | admin
cluster_member
db_member |
| reset_bdb_current_import_status | admin
cluster_member
db_member |
| start_bdb_export | admin
cluster_member
db_member |
| start_bdb_import | admin
cluster_member
db_member |
| start_bdb_recovery | admin
cluster_member
db_member |
| start_cluster_action | admin |
| start_node_action | admin |
| test_ocsp_status | admin |
| update_bdb | admin
cluster_member
db_member |
| update_bdb_alerts | admin
cluster_member
db_member |
| update_bdb_with_action | admin
cluster_member
db_member |
| update_cluster | admin |
| update_crdb | admin
cluster_member
db_member |
| update_ldap_mapping | admin
user_manager |
| update_node | admin |
| update_proxy | admin
user_manager |
| update_redis_acl | admin
user_manager |
| update_role | admin
user_manager |
| update_user | admin
user_manager |
| view_all_bdb_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_bdbs_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_bdbs_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_ldap_mappings_info | admin
user_manager |
| view_all_metrics | admin
cluster_member
cluster_viewer |
| view_all_nodes_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_nodes_checks | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_nodes_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_nodes_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_proxies_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_redis_acls_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_roles_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_shard_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_all_users_info | admin
user_manager |
| view_bdb_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |<a
| view_bdb_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_bdb_recovery_plan | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_bdb_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_cluster_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_cluster_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_cluster_keys | admin
cluster_member
user_manager |
| view_cluster_modules | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_cluster_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_crdb | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_crdb_list | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_crdb_task | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_crdb_task_list | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_debugging_info | admin
cluster_member
db_member
user_manager |
| view_endpoint_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_ldap_config | admin
user_manager |
| view_ldap_mapping_info | admin
user_manager |
| view_license | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_logged_events | admin
cluster_member
cluster_viewer
db_member
user_manager |
| view_node_alerts | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_node_check | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_node_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_node_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_ocsp_config | admin |
| view_ocsp_status | admin |
| view_proxy_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_redis_acl_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_redis_pass | admin
cluster_member
db_member
user_manager |
| view_role_info | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_shard_stats | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_sso | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_status_of_all_node_actions | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_status_of_cluster_action | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_status_of_node_action | admin
cluster_member
cluster_viewer
db_member
db_viewer
user_manager |
| view_user_info | admin
user_manager |


title: Redis Software REST API quick start

summary: Redis Software REST API quick start

title: Overview

text: Redis Software includes a REST API that allows you to automate certain tasks. This article shows you how to send a request to the Redis Software REST API.

title: Fundamentals

text:
No matter which method you use to send API requests, there are a few common concepts to remember.

| Type | Description |
|------|-------------|
| [Authentication]() | Use [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) with your cluster username (email) and password |
| [Ports]() | All calls are made to port 9443 by default |
| [Versions]() | Specify the version in the request [URI](https://en.wikipedia.org/wiki/Uniform_Resource_Identifier) |
| [Headers]() | `Accept` and `Content-Type` should be `application/json` |
| [Response types and error codes]() | A response of `200 OK` means success; otherwise, the request failed due to an error |

For more information, see [Redis Software REST API]().

title: cURL example requests

text:
[cURL](https://curl.se/) is a command-line tool that allows you to send HTTP requests from a terminal.

You can use the following options to build a cURL request:

| Option | Description |
|--------|-------------|
| -X     | Method (GET, PUT, PATCH, POST, or DELETE) |
| -H     | Request header, can be specified multiple times |
| -u     | Username and password information |
| -d     | JSON data for PUT or POST requests |
| -F     | Form data for PUT or POST requests, such as for the [`POST /v1/modules`]() or [`POST /v2/modules`]() endpoint |
| -k     | Turn off SSL  verification |
| -i     | Show headers and status code as well as the response body |

See the [cURL documentation](https://curl.se/docs/) for more information.

title: GET request

text:
Use the following cURL command to get a list of databases with the [GET `/v1/bdbs/`]() endpoint.

[code example]

In the response body, the `uid` is the database ID. You can use the database ID to view or update the database using the API.

For more information about the fields returned by [GET `/v1/bdbs/`](), see the [`bdbs` object]().

title: PUT request

text:
Once you have the database ID, you can use [PUT `/v1/bdbs/`]() to update the configuration of the database.

For example, you can pass the database `uid` 1 as a URL parameter and use the `-d` option to specify the new `name` when you send the request. This changes the database's `name` from `tr01` to `database1`:

[code example]

For more information about the fields you can update with [PUT `/v1/bdbs/`](), see the [`bdbs` object]().

title: Client examples

text:
You can also use client libraries to make API requests in your preferred language.

To follow these examples, you need:

- A [Redis Software]() node
- Python 3 and the [requests](https://pypi.org/project/requests/) Python library
- [node.js](https://nodejs.dev/) and [node-fetch](https://www.npmjs.com/package/node-fetch)

title: Python

text:
[code example]

See the [Python requests library documentation](https://requests.readthedocs.io/en/latest/) for more information.

#### Output

[code example]

title: node.js

text:
[code example]

See the [node-fetch documentation](https://www.npmjs.com/package/node-fetch) for more info.

#### Output

[code example]

title: More info

text:
- [Redis Software REST API]()
- [Redis Software REST API requests]()

code:
$ curl -X GET -H "accept: application/json" \
              -u "[username]:[password]" \
              https://[host][:port]/v1/bdbs -k -i

HTTP/1.1 200 OK
server: envoy
date: Tue, 14 Jun 2022 19:24:30 GMT
content-type: application/json
content-length: 2833
cluster-state-id: 42
x-envoy-upstream-service-time: 25

[
    {
        ...
        "name": "tr01",
        ...
        "uid": 1,
        "version": "6.0.16",
        "wait_command": true
    }
]

section_id: get-request

code:
$ curl -X PUT -H "accept: application/json" \
            -H "content-type: application/json" \
            -u "cameron.bates@redis.com:test123" \
            https://[host]:[port]/v1/bdbs/1 \
            -d '{ "name": "database1" }' -k -i
HTTP/1.1 200 OK
server: envoy
date: Tue, 14 Jun 2022 20:00:25 GMT
content-type: application/json
content-length: 2933
cluster-state-id: 43
x-envoy-upstream-service-time: 159

{
    ...
    "name" : "database1",
    ...
    "uid" : 1,
    "version" : "6.0.16",
    "wait_command" : true
}

section_id: put-request

code:
import json
import requests

# Required connection information - replace with your host, port, username, and password
host = "[host]"
port = "[port]"
username = "[username]"
password = "[password]"

# Get the list of databases using GET /v1/bdbs
bdbs_uri = "https://{}:{}/v1/bdbs".format(host, port)

print("GET {}".format(bdbs_uri))
get_resp = requests.get(bdbs_uri,
        auth = (username, password),
        headers = { "accept" : "application/json" },
        verify = False)

print("{} {}".format(get_resp.status_code, get_resp.reason))
for header in get_resp.headers.keys():
    print("{}: {}".format(header, get_resp.headers[header]))

print("\n" + json.dumps(get_resp.json(), indent=4))

# Rename all databases using PUT /v1/bdbs
for bdb in get_resp.json():
    uid = bdb["uid"] # Get the database ID from the JSON response

    put_uri = "{}/{}".format(bdbs_uri, uid)
    new_name = "database{}".format(uid)
    put_data = { "name" : new_name }

    print("PUT {} {}".format(put_uri, json.dumps(put_data)))

    put_resp = requests.put(put_uri,
        data = json.dumps(put_data),
        auth = (username, password),
        headers = { "content-type" : "application/json" },
        verify = False)

    print("{} {}".format(put_resp.status_code, put_resp.reason))
    for header in put_resp.headers.keys():
        print("{}: {}".format(header, put_resp.headers[header]))

    print("\n" + json.dumps(put_resp.json(), indent=4))

section_id: python

code:
$ python rs_api.py
python rs_api.py
GET https://[host]:[port]/v1/bdbs
InsecureRequestWarning: Unverified HTTPS request is being made to host '[host]'.
Adding certificate verification is strongly advised.
See: https://urllib3.readthedocs.io/en/1.26.x/advanced-usage.html#ssl-warnings
  warnings.warn(
200 OK
server: envoy
date: Wed, 15 Jun 2022 15:49:43 GMT
content-type: application/json
content-length: 2832
cluster-state-id: 89
x-envoy-upstream-service-time: 27

[
    {
        ...
        "name": "tr01",
        ...
        "uid": 1,
        "version": "6.0.16",
        "wait_command": true
    }
]

PUT https://[host]:[port]/v1/bdbs/1 {"name": "database1"}
InsecureRequestWarning: Unverified HTTPS request is being made to host '[host]'.
Adding certificate verification is strongly advised.
See: https://urllib3.readthedocs.io/en/1.26.x/advanced-usage.html#ssl-warnings
  warnings.warn(
200 OK
server: envoy
date: Wed, 15 Jun 2022 15:49:43 GMT
content-type: application/json
content-length: 2933
cluster-state-id: 90
x-envoy-upstream-service-time: 128

{
    ...
    "name" : "database1",
    ...
    "uid" : 1,
    "version" : "6.0.16",
    "wait_command" : true
}

code:
import fetch, { Headers } from 'node-fetch';
import * as https from 'https';

const HOST = '[host]';
const PORT = '[port]';
const USERNAME = '[username]';
const PASSWORD = '[password]';

// Get the list of databases using GET /v1/bdbs
const BDBS_URI = `https://${HOST}:${PORT}/v1/bdbs`;
const USER_CREDENTIALS = Buffer.from(`${USERNAME}:${PASSWORD}`).toString('base64');
const AUTH_HEADER = `Basic ${USER_CREDENTIALS}`;

console.log(`GET ${BDBS_URI}`);

const HTTPS_AGENT = new https.Agent({
    rejectUnauthorized: false
});

const response = await fetch(BDBS_URI, {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Authorization': AUTH_HEADER
    },
    agent: HTTPS_AGENT
});

const responseObject = await response.json();
console.log(`${response.status}: ${response.statusText}`);
console.log(responseObject);

// Rename all databases using PUT /v1/bdbs
for (const database of responseObject) {
    const DATABASE_URI = `${BDBS_URI}/${database.uid}`;
    const new_name = `database${database.uid}`;

    console.log(`PUT ${DATABASE_URI}`);

    const response = await fetch(DATABASE_URI, {
        method: 'PUT',
        headers: {
            'Authorization': AUTH_HEADER,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            'name': new_name
        }),
        agent: HTTPS_AGENT
    });

    console.log(`${response.status}: ${response.statusText}`);
    console.log(await(response.json()));
}

section_id: node-js

code:
$ node rs_api.js
GET https://[host]:[port]/v1/bdbs
200: OK
[
    {
        ...
        "name": "tr01",
        ...
        "slave_ha" : false,
        ...
        "uid": 1,
        "version": "6.0.16",
        "wait_command": true
    }
]
PUT https://[host]:[port]/v1/bdbs/1
200: OK
{
    ...
    "name" : "tr01",
    ...
    "slave_ha" : true,
    ...
    "uid" : 1,
    "version" : "6.0.16",
    "wait_command" : true
}


title: Database actions requests

summary: Database actions requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-db-actions) | `/v1/actions/bdb/{bdb_uid}` | Get the status of a specific database's actions |

title: Get database actions {#get-db-actions}

text:
[code example]

Get the status of all currently executing, pending, or completed state-machine-related actions for a specific database. This API tracks short-lived API requests that return `action_uid`.

#### Required permissions

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

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| bdb_uid | string | Unique database ID |

title: Response {#get-response}

text:
Returns an array of JSON objects with attributes from [actions]() and [state machines]().

Each action contains the following attributes: `name`, `action_uid`, `status`, and `progress`.

#### 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, response provides info about state-machine actions |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | bdb not found |

code: GET /v1/actions/bdb/{bdb_uid}

section_id: get-database-actions-get-db-actions

code: GET /v1/actions/bdb/1

section_id: request-get-request

SMUpdateBDB

status: active

section_id: response-get-response


title: Actions requests

summary: Actions requests

summary: Database actions requests

title: Database actions requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-all-actions) | `/v1/actions` | Get all actions |
| [GET](#get-all-actions-v2) | `/v2/actions` | Get all actions |
| [GET](#get-action) | `/v1/actions/{uid}` | Get a single action |
| [GET](#get-action-v2) | `/v2/actions/{uid}` | Get a single action |

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

text:
[code example]

Get the status of all running, pending, or completed actions on all clusters, nodes, and databases. This API tracks long-lived API requests that return either a `task_id` or an `action_uid`.

This API does not return any information about other actions, such as import, export, and backup. To get info about these actions, use [`GET /v2/actions`](#get-all-actions-v2).

#### Required permissions

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

title: Request {#get-all-request}

title: Response {#get-all-response}

text:
Returns a JSON array of [action objects](), which represent tasks, and an array of [state-machine objects]().

| Field | Type/Value | Description |
|-------|------------|-------------|
| action_uid | string | The action's globally unique identifier |
| name | string | Name of the running or failed state machine |
| progress | float (range: 0-100) | Percent of completed steps for the action |
| status | "pending"
"active"
"completed"
"failed" | The action's status |
| node_uid | string | UID of the node where the operation runs (optional) |
| object_name | string | The object that the action runs on (optional) |
| state | string | The current state of the state machine (optional)  |
| pending_ops | JSON object | List of operations that are waiting to run (optional)
"pending_ops": {
  "3": {
    "heartbeat": integer,
    "snapshot": { ... },
    "last_sample_time": integer,
    "op_name": string,
    "status_code": string,
    "status_description": string,
    "progress": float
  }
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |

Regardless of an action’s source, each action in the response contains the following attributes: `name`, `action_uid`, `status`, and `progress`.

#### Example JSON body

[code example]

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

text:
| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | No error, response provides info about an ongoing action |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (for example, not currently running and no available status of last run).|

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

text:
[code example]

Get the status of all currently running, pending, or completed actions from tasks, state-machines, and other actions, including import, export, and backup. This API tracks long-lived API requests that return either a `task_id` or an `action_uid`.

#### Required permissions

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

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

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

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

The v2 action object includes the following fields:

| Field | Type/Value | Description |
|-------|------------|-------------|
| action_uid | string | The action's globally unique identifier |
| action_type | "task"
"state-machine"
"other" | The action's type |
| creation_time | integer | The action's creation time. Unix timestamp in seconds. |
| name | string | Name of the running or failed state machine |
| progress | float (range: 0-100) | Percent of completed steps for the action |
| status | "queued"
"running"
"completed"
"failed" | The action's status |
| additional_info | JSON object | A dictionary that can include additional information about the action; only included in the response if it contains at least one key-value pair |

The `additional_info` object can contain any of the following fields:

| Field | Type/Value | Description |
|-------|------------|-------------|
| description | string | Short description of the action |
| error | string | A message that describes what error occurred if the action failed |
| object_type | string | The type of object that was processed in the action, such as BDB or node |
| object_uid | string | The unique ID of the object processed in the action |
| pending_ops | JSON object | List of operations that are waiting to run (optional)
"pending_ops": {
  "3": {
    "heartbeat": integer,
    "snapshot": { ... },
    "last_sample_time": integer,
    "op_name": string,
    "status_code": string,
    "status_description": string,
    "progress": float
  }
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: **last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |

Regardless of an action’s source, each action in the response contains the following attributes: `name`, `action_uid`, `creation_time`, `status`, and `progress`.

#### Example JSON body

[code example]

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

title: Get a specific action v1 {#get-action}

text:
[code example]

Get the status of a specific action.

This API does not return any information about other actions, such as import, export, and backup. To get info about these actions, use [`GET /v2/actions/<uid>`](#get-action-v2).

#### Required permissions

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

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | string | The action_uid to check |

title: Response {#get-response}

text:
Returns an [action object]().

| Field | Type/Value | Description |
|-------|------------|-------------|
| action_uid | string | The action's globally unique identifier |
| name | string | Name of the running or failed state machine |
| progress | float (range: 0-100) | Percent of completed steps for the action |
| status | "pending"
"active"
"completed"
"failed" | The action's status |
| node_uid | string | UID of the node where the operation runs (optional) |
| object_name | string | The object that the action runs on (optional) |
| state | string | The current state of the state machine (optional)  |
| pending_ops | JSON object | List of operations that are waiting to run (optional)
"pending_ops": {
  "3": {
    "heartbeat": integer,
    "snapshot": { ... },
    "last_sample_time": integer,
    "op_name": string,
    "status_code": string,
    "status_description": string,
    "progress": float
  }
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |

Regardless of an action’s source, each action contains the following attributes: `name`, `action_uid`, `status`, and `progress`.

#### 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, response provides info about an ongoing action |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Action does not exist (that is, not currently running and no available status of last run) |

title: Get a specific action v2 {#get-action-v2}

text:
[code example]

Get the status of a specific action. This API can also return information about actions like import, export, and backup.

#### Required permissions

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

title: Request {#get-request-v2}

title: Response {#get-response-v2}

text:
Returns a v2 [action object]().

The v2 action object includes the following fields:

| Field | Type/Value | Description |
|-------|------------|-------------|
| action_uid | string | The action's globally unique identifier |
| action_type | "task"
"state-machine"
"other" | The action's type |
| creation_time | integer | The action's creation time. Unix timestamp in seconds. |
| name | string | Name of the running or failed state machine |
| progress | float (range: 0-100) | Percent of completed steps for the action |
| status | "queued"
"running"
"completed"
"failed" | The action's status |
| additional_info | JSON object | A dictionary that can include additional information about the action; only included in the response if it contains at least one key-value pair |

The `additional_info` object can contain any of the following fields:

| Field | Type/Value | Description |
|-------|------------|-------------|
| description | string | Short description of the action |
| error | string | A message that describes what error occurred if the action failed |
| object_type | string | The type of object that was processed in the action, such as BDB or node |
| object_uid | string | The unique ID of the object processed in the action |
| pending_ops | JSON object | List of operations that are waiting to run (optional)
"pending_ops": {
  "3": {
    "heartbeat": integer,
    "snapshot": { ... },
    "last_sample_time": integer,
    "op_name": string,
    "status_code": string,
    "status_description": string,
    "progress": float
  }
}
`pending_ops` is a map where the key is the `shard_id`, and the value is a map that can include the following optional fields:
**heartbeat**: The time, in seconds since the Unix epoch, since the last change in the progress of the operation.
**snapshot**: A map of properties stored by the operation that are needed to run.
**last_sample_time**: The time, in seconds since the Unix epoch, when the last snapshot of the operation was taken.
**op_name**: The name of the operation from the state machine that is running.
**status_code**: The code for the operation's current status.
**status_description**: The operation's current status.
**progress**: The operation's progress in percentage (1 to 100). |

Regardless of an action’s source, each action contains the following attributes: `name`, `action_uid`, `creation_time`, `status`, and `progress`.

#### Example JSON body

[code example]

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

code: GET /v1/actions

section_id: request-get-all-request

status: completed

section_id: response-get-all-response

code: GET /v2/actions

code:
[
    {
        "action_type": "task",
        "action_uid": "6155403f-c26f-40ab-8afc-23ed663973f6",
        "additional_info": {
            "object_type": "node",
            "object_uid": "1"
        },
        "creation_time": 1742595918,
        "name": "retry_bdb",
        "progress": 100.0,
        "status": "completed"
    },
    // Additional task objects
]

code: GET /v1/actions/{uid}

code: GET /v2/actions/{uid}

action_type: task

object_type: node


title: Backup reset status database action requests

summary: Reset database backup status requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT](#put-bdbs-actions-backup-reset-status) | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status |

title: Reset database backup status {#put-bdbs-actions-backup-reset-status}

text:
[code example]

Resets the database's `backup_status` to idle if a backup is not in progress and clears the value of the `backup_failure_reason` field.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [reset_bdb_current_backup_status]() | admin
cluster_member
db_member |

title: Request {#put-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 database |

title: Response {#put-response}

text:
Returns a status code.

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

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. |

section_id: request-put-request


title: Export database action requests

summary: Export database requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-bdbs-actions-export) | `/v1/bdbs/{uid}/actions/export` | Initiate database export |

title: Initiate database export {#post-bdbs-actions-export}

text:
[code example]

Initiate a database export.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [start_bdb_export]() | admin
cluster_member
db_member |

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 |
|-------|------|-------------|
| uid | integer | The unique ID of the database |

#### Body

The request body should contain a JSON object with the following export parameters:

| Field | Type | Description |
|-------|------|-------------|
| export_location | [backup_location/export_location]() object | Details for the export destination. Call [`GET /v1/jsonschema`]() on the bdb object and review the `backup_location` field to retrieve the object's structure.  |
| email_notification | boolean | Enable/disable an email notification on export failure/ completion. (optional) |

##### Example JSON body

[code example]

The above request initiates an export operation to the specified location.

title: Response {#post-response}

text:
Returns a status code.

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

| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. In order to monitor progress, the BDB's `export_status`, `export_progress`, and `export_failure_reason` attributes can be consulted. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. |

code: POST /v1/bdbs/{int: uid}/actions/export

code: POST /v1/bdbs/1/actions/export

section_id: request-post-request

type: url


title: Export resets status database action requests

summary: Reset database export status requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT](#put-bdbs-actions-export-reset-status) | `/v1/bdbs/{uid}/actions/export_reset_status` | Reset database export status |

title: Reset database export status {#put-bdbs-actions-export-reset-status}

text:
PUT /v1/bdbs/{int: uid}/actions/export_reset_status

Resets the database's `export_status` to idle if an export is not in progress and clears the value of the `export_failure_reason` field.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [reset_bdb_current_export_status]() | admin
cluster_member
db_member |

title: Request {#put-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 database |

title: Response {#put-response}


title: Import database action requests

summary: Import database requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-bdbs-actions-import) | `/v1/bdbs/{uid}/actions/import` | Initiate manual dataset import |

title: Initiate manual dataset import {#post-bdbs-actions-import}

text:
[code example]

Initiate a manual import process.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [start_bdb_import]() | admin
cluster_member
db_member |

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 |
| Content-Length | 0 | Length of the request body in octets |

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database |

#### Body

The request _may_ contain a subset of the [BDB JSON object](), which includes the following import-related attributes:

| Field | Type | Description |
|-------|------|-------------|
| dataset_import_sources | array of [dataset_import_sources]() objects | Details for the import sources. Call [`GET /v1/jsonschema`]() on the bdb object and review the `dataset_import_sources` field to retrieve the object's structure.  |
| email_notification | boolean | Enable/disable an email notification on import failure/ completion. (optional) |

Other attributes are not allowed and will cause the request to fail.

##### Example JSON body

General example:

[code example]

This request initiates an import process using `dataset_import_sources` values that were previously configured for the database.

FTP example:

[code example]

SFTP example:

[code example]

AWS S3 example:

[code example]

Google Cloud Storage example:

[code example]

Azure Blob Storage example:

[code example]

title: Response {#post-response}

text: Returns a status code.

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

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. In order to monitor progress, the `import_status`, `import_progress`, and `import_failure_reason` attributes can be consulted. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability. |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. |

code: POST /v1/bdbs/{int: uid}/actions/import

code: POST /v1/bdbs/1/actions/import

type: sftp

bucket_name: backups

subdir: test-db

access_key_id: XXXXXXXXXXXXX

secret_access_key: XXXXXXXXXXXXXXXX

type: gs

client_id: XXXXXXXX

private_key_id: XXXXXXXXXXXXX

private_key: XXXXXXXXXXXXXXXX

code:
{
  "dataset_import_sources": [
    {
      "type": "abs",
      "container": "backups",
      "subdir": "test-db",
      "filename": "<filename>.rdb",
      "account_name": "name",
      "account_key": "XXXXXXXXXXXXXXXX" // Or you can use "sas_token": "XXXXXXXXXXXXXXXXXX" instead
    }
  ]
}


title: Import reset status database action requests

summary: Reset database import status requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT](#put-bdbs-actions-import-reset-status) | `/v1/bdbs/{uid}/actions/import_reset_status` | Reset database import status |

title: Reset database import status {#put-bdbs-actions-import-reset-status}

text:
PUT /v1/bdbs/{int: uid}/actions/import_reset_status

Reset the database’s `import_status` to idle if a backup is not in progress and clears the value of the `import_failure_reason` field.

title: Permissions

text:
| Permission name | Roles |
|-----------------|-------|
| [reset_bdb_current_import_status]() | admin
cluster_member
db_member |

title: Request {#put-request}

title: Response {#put-response}

text: Returns a status code.

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

text:
| Code | Description |
|------|-------------|
| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | The request is accepted and is being processed. |
| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Attempting to perform an action on a nonexistent database. |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not all the modules loaded to the database support 'backup_restore' capability |
| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Database is currently busy with another action. In this context, this is a temporary condition and the request should be reattempted later. |


title: Database actions requests

summary: Database action requests

summary: Reset database backup status requests

summary: Export database requests

title: Export database action requests

summary: Reset database export status requests

summary: Import database requests

title: Import database action requests

summary: Reset database import status requests

summary: Optimize shard placement requests

title: Optimize shards placement database action requests

summary: REST API requests to rebalance database shards

title: Rebalance database requests

summary: REST API requests for database recovery

title: Recover database requests

summary: REST API requests to resume traffic for a database

title: Resume database traffic requests

summary: REST API requests to update database configuration and optimize shard placement

title: Revamp database requests

summary: REST API requests to stop traffic for a database

title: Stop database traffic requests

title: Backup

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT]() | `/v1/bdbs/{uid}/actions/backup_reset_status` | Reset database backup status |

title: Export

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT]() | `/v1/bdbs/{uid}/actions/export_reset_status` | Reset database export status |
| [POST]() | `/v1/bdbs/{uid}/actions/export` | Initiate database export |

title: Import

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT]() | `/v1/bdbs/{uid}/actions/import_reset_status` | Reset database import status |
| [POST]() | `/v1/bdbs/{uid}/actions/import` | Initiate manual dataset import |

title: Optimize shards placement

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET]() | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database  |

title: Rebalance

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT]() | `/v1/bdbs/{uid}/actions/rebalance` | Rebalance database shards |

title: Recover

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET]() | `/v1/bdbs/{uid}/actions/recover` | Get database recovery plan  |
| [POST]() | `/v1/bdbs/{uid}/actions/recover` | Recover database  |

title: Resume traffic

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST]() | `/v1/bdbs/{uid}/actions/resume_traffic` | Resume database traffic |

title: Stop traffic

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST]() | `/v1/bdbs/{uid}/actions/stop_traffic` | Stop database traffic |


summary: Optimize shard placement requests

title: Overview

text:
This REST API path is deprecated as of Redis Software version 7.22. Use [`PUT /v1/bdbs/<uid>/actions/revamp?dry_run=true`]() instead.

| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-bdbs-actions-optimize-shards-placement) | `/v1/bdbs/{uid}/actions/optimize_shards_placement` | Get optimized shards placement for a database  |

title: Get optimized shards placement {#get-bdbs-actions-optimize-shards-placement}

text:
[code example]

Get optimized shards placement for the given database.

#### 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]

#### Query parameters

Include query parameters in a `GET` request to generate an optimized shard placement blueprint for a database, using settings that are different from the database's current configuration.

| Field | Type | Description |
|-------|------|-------------|
| avoid_nodes | list of integers | Comma-separated list of cluster node IDs to avoid when placing the database’s shards and binding its endpoints (for example, `avoid_nodes=1,2`) |
| memory_size | integer (default: 0) | Database memory limit (0 is unlimited), expressed in bytes |
| shards_count | integer, <nobr>(range: 1-512)</nobr> (default: 1) | Number of database server-side shards |
| shards_placement | `dense`
`sparse` | Control the density of shards
 `dense`: Shards reside on as few nodes as possible
 `sparse`: Shards reside on as many nodes as possible |
| bigstore_ram_size | integer (default: 0) | Memory size of bigstore RAM part, expressed in bytes |
| replication | `enabled`
`disabled` | In-memory database replication mode |

The following example request includes `shards_count` and `memory_size` as query parameters:

[code example]

title: Response {#get-response}

text:
To rearrange the database shards, you can submit the blueprint returned in this response body as the `shards_blueprint` field in the [`PUT` `/v1/bdbs/{uid}`](#put-bdbs-rearrange-shards) request.

#### Example JSON body

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Content-Length | 352 | Length of the request body in octets |
| cluster-state-id | 30 | Cluster state ID |

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

| 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) | Database UID does not exist |
| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Not enough resources in the cluster to host the database |

title: Rearrange database shards {#put-bdbs-rearrange-shards}

text:
Use the blueprint returned by the [`GET` `/v1/bdbs/{uid}/actions/optimize_shards_placement`]() request as the value of the `shards_blueprint` field to rearrange the database shards.

To ensure that the optimized shard placement is relevant for the current cluster state, pass the `cluster-state-id`, taken from the response header of the `GET` request, in the [`PUT` `/v1/bdbs/{uid}`]() request headers.

The cluster will reject the update if its state was changed since the optimal shards placement was obtained.

title: Request

text:
#### Example HTTP request

[code example]

#### Headers

| Key | Value | Description |
|-----|-------|-------------|
| Host | cnm.cluster.fqdn | Domain name |
| Accept | application/json | Accepted media type |
| cluster-state-id | 30 | Cluster state ID |

#### Example JSON body

[code example]

If you submit such an optimized blueprint, it may cause strain on the cluster and its resources. Use with caution.

role: master

role: slave

code: PUT /v1/bdbs/1

section_id: request


title: Rebalance database requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [PUT](#put-bdbs-actions-rebalance) | `/v1/bdbs/{uid}/actions/rebalance` | Rebalance database shards |

title: Rebalance database shards {#put-bdbs-actions-rebalance}

text:
[code example]

Distributes the database's shards across nodes based on the database's shard placement policy. See [Shard placement policy]() for more information about shard placement and available policies.

#### Required permissions

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

title: Request {#put-request}

text:
#### Example HTTP request

[code example]

Dry-run example:

[code example]

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database to rebalance. |

#### Query parameters

| Field | Type | Description |
|-------|------|-------------|
| dry_run | boolean | If true, returns the blueprint of the rebalanced database without actually changing the database. Default is false. |
| only_failovers | boolean | If true, only runs failovers and no migrations. Default is false. |
| max_operations | integer | Optional. The number of operations to do. Only works if `only_failovers` is true. If not provided, uses the number of the database's primary-replica pairs. |

title: Response {#put-response}

text:
- If `dry_run` is `false`, returns an `action_uid`. You can track the action's progress with a [`GET /v1/actions/<action_uid>`]() request.

- If `dry_run` is `true`, returns the balanced shards' blueprint.

  You can rearrange shards according to this blueprint if you use it in the `shards_blueprint` field of a [rearrange database shards]() request.

  You should also pass the rebalance shards' `cluster-state-id` response header as a request header of the rearrange database shards request to make sure the optimized shard placement is relevant for the current cluster state. The cluster will reject the update if its state changed since the optimal shards placement blueprint was generated.

#### Example response

If `dry_run` is `false`:

[code example]

If `dry_run` is `true`:

[code example]

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

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | When `dry_run` is false: The request is accepted and is being processed. When the database is recovered, its status will become active.<br />When `dry_run` is true: No error. |
| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad request. Invalid input parameters. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. |
| [406 Not Acceptable](https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable) | Not enough resources in the cluster to host the database. |
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Database is currently busy with another action, recovery is already in progress, or is not in a recoverable state. |
| [500 Internal Server Error](https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error) | Internal server error. |

code: PUT /v1/bdbs/1/actions/rebalance

section_id: response-put-response


title: Recover database requests

summary: REST API requests for database recovery

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [GET](#get-bdbs-actions-recover) | `/v1/bdbs/{uid}/actions/recover` | Get database recovery plan  |
| [POST](#post-bdbs-actions-recover) | `/v1/bdbs/{uid}/actions/recover` | Recover database  |

title: Get recovery plan {#get-bdbs-actions-recover}

text:
[code example]

Fetches the recovery plan for a database. The recovery plan provides information about the recovery status, such as whether recovery is possible, and details on available files to use for recovery.

#### Required permissions

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

title: Request {#get-request}

text:
#### Example HTTP request

[code example]

#### URL parameters

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

title: Response {#get-response}

text:
Returns a JSON object that represents the database's recovery plan, including recovery files and status.

#### 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 UID does not exist. |

title: Recover database {#post-bdbs-actions-recover}

text:
[code example]

Initiates [recovery for a database]() in a recoverable state where all the database's files are available after [cluster recovery]().

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [start_bdb_recovery]() | admin
cluster_member
db_member |

title: Request {#post-request}

text:
The request body can either be empty or include a recovery plan.

If the request body is empty, the database will be recovered automatically:

- Databases with no persistence are recovered with no data.

- Persistent files such as AOF or RDB will be loaded from their expected storage locations where replica or primary shards were last active.

- If persistent files are not found where expected but can be located on other cluster nodes, they will be used.

#### Example HTTP request

[code example]

#### Example request body

[code example]

#### URL parameters

| Field | Type | Description |
|-------|------|-------------|
| uid | integer | The unique ID of the database to recover. |

title: Response {#post-response}

text:
Returns a status code. Also returns a JSON object with an `action_uid` in the request body if successful.

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

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request is accepted and is being processed. When the database is recovered, its status will become `active`. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. |
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Database is currently busy with another action, recovery is already in progress, or is not in a recoverable state. |

code: GET /v1/bdbs/{int: uid}/actions/recover

code: GET /v1/bdbs/1/actions/recover

shard_role: master

shard_role: slave

status: ready

code: POST /v1/bdbs/1/actions/recover


title: Resume database traffic requests

title: Overview

text:
| Method | Path | Description |
|--------|------|-------------|
| [POST](#post-bdbs-actions-resume-traffic) | `/v1/bdbs/{uid}/actions/resume_traffic` | Resume database traffic |

title: Resume database traffic {#post-bdbs-actions-resume-traffic}

text:
[code example]

Resume traffic handling for the database.

Use this action to resume read and write traffic on a database, where traffic was previously paused using the [`stop_traffic`]() action.

#### Required permissions

| Permission name | Roles |
|-----------------|-------|
| [update_bdb_with_action]() | admin
cluster_member
db_member |

title: Request {#post-request}

title: Response {#post-response}

text:
Returns a JSON object with an `action_uid`. You can track the action's progress with a [`GET /v1/actions/<action_uid>`]() request.

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

| Code | Description |
|------|-------------|
| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | The request is accepted and is being processed. The database state will be `active-change-pending` until the request has been fully processed. |
| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | Attempting to perform an action on a nonexistent database. |
| [409 Conflict](https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict) | Attempting to change a database while it is busy with another configuration change. This is a temporary condition, and the request should be reattempted later. |

code: POST /v1/bdbs/1/actions/resume_traffic