R-NACOS Nacos V1 Open API

Overview

This document describes the R-NACOS HTTP Open API endpoints under the /nacos/v1 prefix, including configuration, naming, namespace, and cluster management. These endpoints are compatible with the Nacos 1.x and 2.x SDK protocols.

Base URL: http://127.0.0.1:8848

---

1. Configuration Management

Configuration management endpoints use the prefix /nacos/v1/cs 。

1. Retrieve Configuration

Endpoint: GET /nacos/v1/cs/configs

Description: Retrieve a configuration, or search configurations using fuzzy or exact matching.

Request Parameters

Parameter	Type	Required	Description
dataId	string	Yes	Configuration ID
group	string	No	Configuration group; defaults to DEFAULT_GROUP
tenant	string	No	Namespace ID; empty by default (public)
search	string	No	Search type: blur or accurate . Omit to retrieve one configuration
pageNo	number	No	Page number; defaults to 1 for searches
pageSize	number	No	Page size for searches

Response

When retrieving one configuration:

• Success: returns the configuration body; response headers include content-md5 and the corresponding Content-Type
• Failure: returns config data not exist

When searching configurations ( search=blur or search=accurate ):

Parameter	Type	Description
totalCount	number	Total records
pageNumber	number	Current page number
pagesAvailable	number	Total pages
pageItems	array	Configuration list
pageItems[].tenant	string	Namespace
pageItems[].group	string	Group
pageItems[].dataId	string	Configuration ID
pageItems[].content	string	Configuration content
pageItems[].md5	string	MD5 checksum

Example

Retrieve One Configuration:

curl -X GET "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=test.yaml&group=DEFAULT_GROUP&tenant="

The response is the configuration text; response headers include content-md5 .

Fuzzy Configuration Search:

curl -X GET "http://127.0.0.1:8848/nacos/v1/cs/configs?search=blur&dataId=test&pageNo=1&pageSize=10"

Response:

{"totalCount":1,"pageNumber":1,"pagesAvailable":1,"pageItems":[{"tenant":"","group":"DEFAULT_GROUP","dataId":"test.yaml","content":"key: value","md5":"d41d8cd98f00b204e9800998ecf8427e"}]}

---

2. Publish Configuration

Endpoint: POST/PUT /nacos/v1/cs/configs

Description: Create or update a configuration. Both POST and PUT are supported.

Request Parameters

Parameter	Type	Required	Description
dataId	string	Yes	Configuration ID
group	string	No	Configuration group; defaults to DEFAULT_GROUP
tenant	string	No	Namespace ID; empty by default
content	string	Yes	Configuration content
type	string	No	Configuration type, such as yaml , json , properties , text , html , or xml
desc	string	No	Configuration description

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns true
• Failure: returns an error message

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs" -d "dataId=test.yaml&group=DEFAULT_GROUP&content=key:%20value&type=yaml"

Response:

true

---

3. Delete Configuration

Endpoint: DELETE /nacos/v1/cs/configs

Description: Delete the specified configuration.

Request Parameters

Parameter	Type	Required	Description
dataId	string	Yes	Configuration ID
group	string	No	Configuration group; defaults to DEFAULT_GROUP
tenant	string	No	Namespace ID; empty by default

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns true
• Failure: returns an error message

Example

curl -X DELETE "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=test.yaml&group=DEFAULT_GROUP"

Response:

true

---

4. Watch Configurations

Endpoint: POST /nacos/v1/cs/configs/listener

Description: Long-poll for configuration changes. When a watched configuration changes, the server returns its configuration key.

Request Parameters

Parameter	Type	Required	Description
Listening-Configs	string	Yes	Configurations to watch, formatted as dataId^2Group^2tenant^1md5...

Request Headers

Parameter	Type	Required	Description
Long-Pulling-Timeout	string	No	Long-poll timeout in milliseconds; range: 10000-120000

Response

• Changes detected: returns the changed configuration keys
• No changes: returns an empty string

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs/listener" \
  -H "Long-Pulling-Timeout: 30000" \
  -d "Listening-Configs=test.yaml%02DEFAULT_GROUP%02%01d41d8cd98f00b204e9800998ecf8427e"

The response is the changed configuration key (if any):

test.yaml^2DEFAULT_GROUP^2

---

2. Naming: Instances

Instance management endpoints use the prefix /nacos/v1/ns/instance 。

5. Register or Update an Instance

Endpoint: POST/PUT/PATCH /nacos/v1/ns/instance

Description: Register an instance or update an existing instance. POST registers; PUT and PATCH update.

Request Parameters

Parameter	Type	Required	Description
ip	string	Yes	Instance IP
port	number	Yes	Instance port
serviceName	string	Yes	Service name in groupName@@serviceName format
namespaceId	string	No	Namespace ID; empty by default
weight	number	No	Weight; defaults to 1.0
enabled	string	No	Whether enabled ( true / false ); defaults to true
healthy	string	No	Whether healthy（used only for updates）
ephemeral	string	No	Whether the instance is ephemeral ( true / false ); defaults to true
metadata	string	No	Instance metadata as JSON, for example {"version":"v1"}
clusterName	string	No	Cluster name; defaults to DEFAULT
groupName	string	No	Group name，may be supplied through serviceName or separately

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns ok
• Failure: returns an error message

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/ns/instance" \
  -d "ip=127.0.0.1&port=8080&serviceName=DEFAULT_GROUP@@my-service&weight=1.0&enabled=true&ephemeral=true&metadata=%7B%22version%22%3A%22v1%22%7D"

Response:

ok

---

6. Deregister an Instance

Endpoint: DELETE /nacos/v1/ns/instance

Description: Deregister (delete) the specified instance.

Request Parameters

Parameter	Type	Required	Description
ip	string	Yes	Instance IP
port	number	Yes	Instance port
serviceName	string	Yes	Service name in groupName@@serviceName format
namespaceId	string	No	Namespace ID; empty by default
clusterName	string	No	Cluster name; defaults to DEFAULT
ephemeral	string	No	Whether the instance is ephemeral
groupName	string	No	Group name

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns ok
• Failure: returns an error message

Example

curl -X DELETE "http://127.0.0.1:8848/nacos/v1/ns/instance?ip=127.0.0.1&port=8080&serviceName=DEFAULT_GROUP@@my-service"

Response:

ok

---

7. Get Instance Details

Endpoint: GET /nacos/v1/ns/instance

Description: Get details for the specified instance.

Request Parameters

Parameter	Type	Required	Description
ip	string	Yes	Instance IP
port	number	Yes	Instance port
serviceName	string	Yes	Service name in groupName@@serviceName format
namespaceId	string	No	Namespace ID; empty by default
clusterName	string	No	Cluster name
groupName	string	No	Group name

Response

Parameter	Type	Description
service	string	Fully qualified service name
ip	string	Instance IP
port	number	Instance port
clusterName	string	Cluster name
weight	number	Weight
healthy	boolean	Whether healthy
instanceId	string	Unique instance ID
metadata	object	Instance metadata
marked	boolean	Whether marked
enabled	boolean	Whether enabled
serviceName	string	Service name
ephemeral	boolean	Whether the instance is ephemeral

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/instance?ip=127.0.0.1&port=8080&serviceName=DEFAULT_GROUP@@my-service"

Response:

{"service":"DEFAULT_GROUP@@my-service","ip":"127.0.0.1","port":8080,"clusterName":"DEFAULT","weight":1.0,"healthy":true,"instanceId":"127.0.0.1#8080#DEFAULT#DEFAULT_GROUP@@my-service","metadata":{},"marked":true,"enabled":true,"serviceName":"DEFAULT_GROUP@@my-service","ephemeral":true}

---

8. Instance Heartbeat

Endpoint: PUT /nacos/v1/ns/instance/beat

Description: Send a heartbeat to keep an ephemeral instance alive.

Request Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service name in groupName@@serviceName format
namespaceId	string	No	Namespace ID; empty by default
clusterName	string	No	Cluster name
groupName	string	No	Group name
ephemeral	string	No	Whether the instance is ephemeral
beat	string	No	Heartbeat data as JSON
ip	string	Conditional	Instance IP（required when beat is empty）
port	number	Conditional	Instance port（required when beat is empty）

beat Parameter JSON Structure:

Parameter	Type	Description
cluster	string	Cluster name
ip	string	Instance IP
port	number	Instance port
metadata	object	Metadata
period	number	Heartbeat interval in milliseconds
scheduled	boolean	Whether scheduled
serviceName	string	Service name
stopped	boolean	Whether stopped
weight	number	Weight

Response

Parameter	Type	Description
responseCode	number	Response code; 0 indicates success
clientBeatInterval	number	Recommended client heartbeat interval in milliseconds
lightBeatEnabled	boolean	Whether lightweight heartbeats are enabled

Example

curl -X PUT "http://127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=DEFAULT_GROUP@@my-service&ip=127.0.0.1&port=8080"

Response:

{"responseCode":0,"clientBeatInterval":5000,"lightBeatEnabled":true}

---

9. List Instances

Endpoint: GET /nacos/v1/ns/instance/list

Description: List instances for the specified service.

Request Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service name in groupName@@serviceName format
namespaceId	string	No	Namespace ID; empty by default
groupName	string	No	Group name
clusters	string	No	Cluster names separated by commas
healthyOnly	string	No	Return only healthy instances ( true / false ); defaults to true
clientIP	string	No	Client IP
udpPort	string	No	UDP port

Response

Returns the instance list as JSON in the HostReactor format defined by the Nacos protocol.

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=DEFAULT_GROUP@@my-service&healthyOnly=true"

The response is the service instance list as a JSON string.

---

3. Naming: Services

Service management endpoints use the prefix /nacos/v1/ns/service 。

10. Create or Update a Service

Endpoint: POST/PUT /nacos/v1/ns/service

Description: Create or update service information.

Request Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service name
groupName	string	No	Group name; defaults to DEFAULT_GROUP
namespaceId	string	No	Namespace ID; empty by default
protectThreshold	number	No	Protection threshold; defaults to 0.0
metadata	string	No	Service metadata，JSON format
selector	string	No	Selector

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns ok
• Failure: returns an error message

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/ns/service" \
  -d "serviceName=my-service&groupName=DEFAULT_GROUP&protectThreshold=0.5&metadata=%7B%22version%22%3A%22v1%22%7D"

Response:

ok

---

11. Delete a Service

Endpoint: DELETE /nacos/v1/ns/service

Description: Delete the specified service.

Request Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service name
groupName	string	No	Group name; defaults to DEFAULT_GROUP
namespaceId	string	No	Namespace ID; empty by default

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns ok
• Failure: returns an error message

Example

curl -X DELETE "http://127.0.0.1:8848/nacos/v1/ns/service?serviceName=my-service&groupName=DEFAULT_GROUP"

Response:

ok

---

12. Get Service Details

Endpoint: GET /nacos/v1/ns/service

Description: Get details for the specified service.

Request Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service name in groupName@@serviceName format
namespaceId	string	No	Namespace ID; empty by default

Response

Parameter	Type	Description
namespaceId	string	Namespace ID
groupName	string	Group name
name	string	Service name
protectThreshold	number	Protection threshold
metadata	object	Service metadata
selector	object	Selector information
clusters	array	Cluster list
clusters[].name	string	Cluster name
clusters[].healthChecker	object	Health-check configuration
clusters[].metadata	object	Cluster metadata

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/service?serviceName=DEFAULT_GROUP@@my-service"

Response:

{"namespaceId":"","groupName":"DEFAULT_GROUP","name":"my-service","protectThreshold":0.0,"metadata":{},"selector":{"type":"none","contextType":"NONE"},"clusters":[{"name":"DEFAULT","healthChecker":{"type":"TCP"},"metadata":{}}]}

---

13. List Services

Endpoint: GET /nacos/v1/ns/service/list

Description: List services in the specified namespace with pagination.

Request Parameters

Parameter	Type	Required	Description
pageNo	number	No	Page number; defaults to 1
pageSize	number	No	Page size
namespaceId	string	No	Namespace ID; empty by default
groupName	string	No	Group name; defaults to DEFAULT_GROUP
serviceName	string	No	Service name (optional query condition)

Response

Parameter	Type	Description
count	number	Total count
doms	array	Service namelist

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=10&namespaceId="

Response:

{"count":2,"doms":["DEFAULT_GROUP@@my-service","DEFAULT_GROUP@@another-service"]}

---

14. List Service Subscribers

Endpoint: GET /nacos/v1/ns/service/subscribers

Description: List subscribers to the specified service with pagination.

Request Parameters

Parameter	Type	Required	Description
pageNo	number	No	Page number; defaults to 1
pageSize	number	No	Page size
namespaceId	string	No	Namespace ID; empty by default
groupName	string	No	Group name
serviceName	string	Yes	Service name

Response

Parameter	Type	Description
count	number	Total count
subscribers	array	Subscriber information list

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/service/subscribers?serviceName=DEFAULT_GROUP@@my-service&pageNo=1&pageSize=10"

Response:

{"count":1,"subscribers":[{"addr":"127.0.0.1","ip":"127.0.0.1","port":0,"serviceName":"DEFAULT_GROUP@@my-service","agent":"nacos-sdk-rust","namespace":"","groupName":"DEFAULT_GROUP"}]}

---

4. Naming: Operations

Operations endpoints use the prefix /nacos/v1/ns/operator 。

15. Get System Switches

Endpoint: GET /nacos/v1/ns/operator/switches

Description: Get the naming service system-switch configuration. R-NACOS returns default mock data for compatibility with the Nacos SDK.

Request Parameters

None

Response

Returns a mock JSON system-switch object with these primary fields:

Parameter	Type	Description
masters	null	Primary-node list
defaultPushCacheMillis	number	default push cache duration
clientBeatInterval	number	client heartbeat interval
defaultCacheMillis	number	default cache duration
healthCheckEnabled	boolean	Whether enabled Health Check
distroEnabled	boolean	Whether enabled distribution
pushEnabled	boolean	Whether enabled push
lightBeatEnabled	boolean	Whether lightweight heartbeats are enabled
defaultInstanceEphemeral	boolean	default whether instances are ephemeral
name	string	Service name identifier（ R-NACOS ）

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/operator/switches"

The response is the system-switch configuration JSON.

---

16. Update System Switches

Endpoint: PUT /nacos/v1/ns/operator/switches

Description: Update system-switch configuration. The R-NACOS mock implementation returns success directly.

Request Parameters

See the Nacos switch parameters.

Response

• Success: returns ok

Example

curl -X PUT "http://127.0.0.1:8848/nacos/v1/ns/operator/switches" -d "entry=pushEnabled&value=true"

Response:

ok

---

17. Get Operations Metrics

Endpoint: GET /nacos/v1/ns/operator/metrics

Description: Get operational metrics for the naming service. R-NACOS returns mock data for compatibility with the Nacos SDK.

Request Parameters

None

Response

Parameter	Type	Description
status	string	Service status, always UP

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/operator/metrics"

Response:

{"status":"UP"}

---

5. Naming: Catalog

Catalog endpoints use the prefix /nacos/v1/ns/catalog 。

18. List Catalog Services with Pagination

Endpoint: GET /nacos/v1/ns/catalog/services

Description: List services with pagination and return service statistics.

Request Parameters

Parameter	Type	Required	Description
pageNo	number	No	Page number; defaults to 1
pageSize	number	No	Page size
namespaceId	string	No	Namespace ID
groupNameParam	string	No	Group name（fuzzy query）
serviceNameParam	string	No	Service name（fuzzy query）

Response

Parameter	Type	Description
count	number	Total count
serviceList	array	Service list
serviceList[].name	string	Service name
serviceList[].groupName	string	Group name
serviceList[].clusterCount	number	Cluster count
serviceList[].ipCount	number	Instance count
serviceList[].healthyInstanceCount	number	Healthy instance count
serviceList[].triggerFlag	boolean	Trigger flag
serviceList[].metadata	string	Metadata JSON
serviceList[].protectThreshold	number	Protection threshold

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/catalog/services?pageNo=1&pageSize=10&namespaceId="

Response:

{"count":1,"serviceList":[{"name":"my-service","groupName":"DEFAULT_GROUP","clusterCount":1,"ipCount":2,"healthyInstanceCount":2,"triggerFlag":false,"metadata":"{}","protectThreshold":0.0}]}

---

19. List Catalog Instances with Pagination

Endpoint: GET /nacos/v1/ns/catalog/instances

Description: List instances for the specified service with pagination.

Request Parameters

Parameter	Type	Required	Description
serviceName	string	Yes	Service name in groupName@@serviceName format
namespaceId	string	No	Namespace ID
groupName	string	No	Group name
clusterName	string	No	Cluster name
pageNo	number	No	Page number; defaults to 1
pageSize	number	No	Page size，default 20

Response

Parameter	Type	Description
count	number	Total count
list	array	Instance list
list[].service	string	Fully qualified service name
list[].ip	string	Instance IP
list[].port	number	Instance port
list[].clusterName	string	Cluster name
list[].weight	number	Weight
list[].healthy	boolean	Whether healthy
list[].instanceId	string	Instance ID
list[].metadata	object	Instance metadata
list[].marked	boolean	Whether marked
list[].enabled	boolean	Whether enabled
list[].serviceName	string	Service name
list[].ephemeral	boolean	Whether the instance is ephemeral

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/ns/catalog/instances?serviceName=DEFAULT_GROUP@@my-service&pageNo=1&pageSize=10"

Response:

{"count":1,"list":[{"service":"DEFAULT_GROUP@@my-service","ip":"127.0.0.1","port":8080,"clusterName":"DEFAULT","weight":1.0,"healthy":true,"instanceId":"127.0.0.1#8080#DEFAULT#DEFAULT_GROUP@@my-service","metadata":{},"marked":true,"enabled":true,"serviceName":"DEFAULT_GROUP@@my-service","ephemeral":true}]}

---

6. Namespace Management

20. List Namespaces (V1 Console)

Endpoint: GET /nacos/v1/console/namespaces

Description: List all namespaces.

Request Parameters

None

Response

Parameter	Type	Description
code	number	Response code
message	string	Response message
data	array	Namespacelist
data[].namespace	string	Namespace ID
data[].namespaceShowName	string	Namespace Display name
data[].namespaceDesc	string	NamespaceDescription
data[].quota	number	Quota
data[].configCount	number	Configuration count
data[].type	number	Type (0: system, 2: custom)

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/console/namespaces"

Response:

{"code":0,"message":"success","data":[{"namespace":"","namespaceShowName":"public","namespaceDesc":null,"quota":200,"configCount":0,"type":0},{"namespace":"dev","namespaceShowName":"Development Environment","namespaceDesc":null,"quota":200,"configCount":5,"type":2}]}

---

21. Create a Namespace (V1 Console)

Endpoint: POST /nacos/v1/console/namespaces

Description: Create a namespace.

Request Parameters

Parameter	Type	Required	Description
customNamespaceId	string	No	Custom namespace ID; a UUID is generated when omitted
namespaceName	string	Yes	Namespace name
namespaceDesc	string	No	NamespaceDescription

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns true
• Failure: returns an error message

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/console/namespaces" -d "customNamespaceId=dev&namespaceName=Development Environment&namespaceDesc=Development EnvironmentNamespace"

Response:

true

---

22. Update a Namespace (V1 Console)

Endpoint: PUT /nacos/v1/console/namespaces

Description: Update the specified namespace.

Request Parameters

Parameter	Type	Required	Description
namespace	string	Yes	Namespace ID
namespaceShowName	string	Yes	Namespace Display name
namespaceDesc	string	No	NamespaceDescription

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns true
• Failure: returns an error message

Example

curl -X PUT "http://127.0.0.1:8848/nacos/v1/console/namespaces" -d "namespace=dev&namespaceShowName=Development EnvironmentV2&namespaceDesc=Updated description"

Response:

true

---

23. Delete a Namespace (V1 Console)

Endpoint: DELETE /nacos/v1/console/namespaces

Description: Delete the specified namespace.

Request Parameters

Parameter	Type	Required	Description
namespaceId	string	Yes	Namespace ID

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

• Success: returns true
• Failure: returns an error message

Example

curl -X DELETE "http://127.0.0.1:8848/nacos/v1/console/namespaces?namespaceId=dev"

Response:

true

---

24. List Namespaces (V2 Console)

Endpoint: GET /nacos/v2/console/namespace/list

Description: List all namespaces using the V2 response format.

Request Parameters

None

Response

Parameter	Type	Description
code	number	Response code; 0 indicates success
message	string	Response message
data	array	Namespacelist
data[].namespace	string	Namespace ID
data[].namespaceShowName	string	Namespace Display name
data[].namespaceDesc	string	NamespaceDescription
data[].quota	number	Quota
data[].configCount	number	Configuration count
data[].type	number	Type

Example

curl -X GET "http://127.0.0.1:8848/nacos/v2/console/namespace/list"

Response:

{"code":0,"message":"success","data":[{"namespace":"","namespaceShowName":"public","namespaceDesc":null,"quota":200,"configCount":0,"type":0}]}

---

25. Get Namespace Details (V2 Console)

Endpoint: GET /nacos/v2/console/namespace

Description: Get details for the specified namespace.

Request Parameters

Parameter	Type	Required	Description
namespaceId	string	Yes	Namespace ID

Parameters may be supplied through the query string or a form-urlencoded request body.

Response

Parameter	Type	Description
code	number	Response code
message	string	Response message
data	object	Namespace details
data.namespace	string	Namespace ID
data.namespaceShowName	string	Display name
data.namespaceDesc	string	Description
data.quota	number	Quota
data.configCount	number	Configuration count
data.type	number	Type

Example

curl -X GET "http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=dev"

---

26. Create a Namespace (V2 Console)

Endpoint: POST /nacos/v2/console/namespace

Description: Create a namespace using the V2 response format.

Request Parameters

Parameter	Type	Required	Description
customNamespaceId	string	No	Custom namespace ID
namespaceName	string	Yes	Namespace name
namespaceDesc	string	No	NamespaceDescription

Response

Parameter	Type	Description
code	number	Response code; 0 indicates success
message	string	Response message
data	boolean	Operation result

Example

curl -X POST "http://127.0.0.1:8848/nacos/v2/console/namespace" -d "customNamespaceId=dev&namespaceName=Development Environment"

Response:

{"code":0,"message":"success","data":true}

---

27. Update a Namespace (V2 Console)

Endpoint: PUT /nacos/v2/console/namespace

Description: Update a namespace using the V2 response format.

Request Parameters

Parameter	Type	Required	Description
namespace	string	Yes	Namespace ID
namespaceShowName	string	Yes	Display name
namespaceDesc	string	No	Description

Response

Parameter	Type	Description
code	number	Response code
message	string	Response message
data	boolean	Operation result

Example

curl -X PUT "http://127.0.0.1:8848/nacos/v2/console/namespace" -d "namespace=dev&namespaceShowName=Development EnvironmentV2"

---

28. Delete a Namespace (V2 Console)

Endpoint: DELETE /nacos/v2/console/namespace

Description: Delete a namespace using the V2 response format.

Request Parameters

Parameter	Type	Required	Description
namespaceId	string	Yes	Namespace ID

Response

Parameter	Type	Description
code	number	Response code
message	string	Response message
data	boolean	Operation result

Example

curl -X DELETE "http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=dev"

---

7. Health Checks

29. Health Check

Endpoint: GET /nacos/v1/console/health/readiness

Description: Check whether the service is ready.

Request Parameters

None

Response

• Ready: returns OK
• Not ready: returns error: <Error message> (HTTP 503)
• Error: returns request health_manager error （HTTP 500）

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/console/health/readiness"

Response:

OK

---

30. General Health Check

Endpoint:

• GET /health
• GET /nacos/health

Description: Check service health.

Request Parameters

None

Response

• Healthy: returns success
• Unhealthy: returns error: <Error message> (HTTP 503)

Example

curl -X GET "http://127.0.0.1:8848/health"

---

31. Export Metrics

Endpoint:

• GET /nacos/metrics

Description: Export metrics in Prometheus format.

Request Parameters

None

Response

Returns Prometheus metrics as text/plain .

Example

curl -X GET "http://127.0.0.1:8848/nacos/metrics"

---

8. Raft Cluster Management

Raft cluster management endpoints use the prefix /nacos/v1/raft 。

32. Join a Cluster Node

Endpoint: POST /nacos/v1/raft/joinnode

Description: Add a new node to the Raft cluster as a learner.

Request Parameters

See the Raft cluster-management parameters.

Response

Returns the operation result.

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/raft/joinnode" -d "..."

---

33. Change Cluster Membership

Endpoint: POST /nacos/v1/raft/change-membership

Description: Change Raft cluster membership.

Request Parameters

See the Raft cluster-management parameters.

Response

Returns the operation result.

Example

curl -X POST "http://127.0.0.1:8848/nacos/v1/raft/change-membership" -d "..."

---

34. Get Raft Metrics

Endpoint: GET /nacos/v1/raft/metrics

Description: Get Raft cluster metrics.

Request Parameters

None

Response

Returns Raft cluster metrics.

Example

curl -X GET "http://127.0.0.1:8848/nacos/v1/raft/metrics"

---

35. Disable Raft Writes

Endpoint: POST /nacos/v1/raft/close-write

Description: Put this node into the Raft write-disabled state. The node then rejects all Raft writes and communication, including log commits, replication, voting, log appends, and snapshot installation. This safely isolates it from the cluster write path and is useful before shutdown, backup, or migration. This endpoint requires no authentication; its safety depends on the close_raft_mark marker file, so only someone with filesystem access can trigger it.

This operation is one-way. After writes are disabled, no endpoint can restore them; restart the node to reload it.

Request Parameters

None。

Before calling the endpoint, manually create an empty close_raft_mark file in this node's local data directory. The directory is the startup local_db_dir , resolved in this order: RNACOS_DATA_DIR , RNACOS_CONFIG_DB_DIR , then the default ( /data/r-nacos/nacos_db in Docker or ~/.local/share/r-nacos/nacos_db on local Linux/macOS). The {local_db_dir}/close_raft_mark file is physical confirmation of this dangerous operation.

Response

Returns JSON:

Field	Type	Description
ok	int	1 indicates that writes were successfully disabled; 0 indicates that the operation was not performed because the marker file is missing
msg	string	Returned only when ok=0 ; instructs the caller to create the marker file first

Example

First create the marker file (using the default Docker directory here):

touch /data/r-nacos/nacos_db/close_raft_mark

Call the endpoint:

curl -X POST "http://127.0.0.1:8848/nacos/v1/raft/close-write"

Successful response:

{"ok":1}

Response when the marker file is missing (HTTP 200; local_db_dir is the actual data directory):

{"ok":0,"msg":"Before running, create the corresponding marker file in the specified directory (/data/r-nacos/nacos_db) create the corresponding marker file close_raft_mark"}

Notes

• This endpoint requires no authentication and relies entirely on the close_raft_mark marker file as a physical safeguard.
• The write-disabled state is one-way. Restart the node to reload it after triggering this operation. Use it only when writes must be frozen.
• Write blocking affects only the current node. If it is the leader, the cluster cannot complete writes through it.

---

9. Data Backup

36. Export a Data Backup

Endpoint: GET /rnacos/backup

Description: Export an R-NACOS data backup. RNACOS_BACKUP_TOKEN must be configured.

Request Parameters

Parameter	Type	Required	Description
token	string	Yes	Backup token; must match RNACOS_BACKUP_TOKEN

Response

• Success: returns the data backup as a binary stream
• Backup disabled: returns backup api is not open （HTTP 500）
• Token mismatch: returns backup token is not matched （HTTP 500）

Example

curl -X GET "http://127.0.0.1:8848/rnacos/backup?token=your_backup_token" -o backup.zip

Notes

• Set the RNACOS_BACKUP_TOKEN environment variable first
• The backup token cannot be empty; otherwise the backup endpoint is unavailable