Open API Guide

• Configuration Management

  • Get configurations
  • Listen for configurations
  • Publish configuration
  • Delete configuration
  • Query list of history configuration
  • Query the history details of the configuration
  • Query the previous version of the configuration

• Service Discovery

  • Register instance
  • Deregister instance
  • Modify instance
  • Query instances
  • Query instance detail
  • Send instance beat
  • Create service
  • Delete service
  • Update service
  • Query service
  • Query service list
  • Query system switches
  • Update system switch
  • Query system metrics
  • Query server list
  • Query the leader of current cluster
  • Update instance health status
  • Batch update instance metadata(Beta)
  • Batch delete instance metadata(Beta)

• Namespace

  • Get namespace
  • Create namespace
  • Update namespace
  • Delete namespace

Configuration Management

Get configurations

Description

This API is used to get configurations in Nacos.

Request type

GET

Request URL

/nacos/v1/cs/configs

Request parameters

Name	Type	Required	Description
tenant	string	No	Tenant information. It corresponds to the Namespace ID field in Nacos.
dataId	string	Yes	Configuration ID
group	string	Yes	Configuration group

Return parameters

Parameter type	Description
String	Configuration value

Error codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Example

• Request example

  curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.example&group=com.alibaba.nacos'
  

• Return example

  contentTest

Listen for configurations

Description

This API is used to listen for configurations in Nacos to capture configuration changes. In case of any configuration changes, you can use the Get Configurations API to obtain the latest value of the configuration and dynamically refresh the local cache.

A listener is registered using an asynchronous servlet. The nature of registering a listener is to compare the configuration value and the MD5 value of it with that of the backend. If the values differ, the inconsistent configuration is returned immediately. Otherwise, an empty string is returned after 30 seconds.

Request type

POST

Request URL

/nacos/v1/cs/configs/listener

Request parameters

Name	Type	Required	Description
Listening-Configs	string	No	A request to listen for data packets. Format : dataId^group^2contentMD5^tenant^1 or dataId^group^2contentMD5^1. dataId : Configuration ID group : Configuration group contentMD5 : The MD5 value of the configuration tenant : Tenant information. It corresponds to the Namespace field in Nacos (not must)
Listening-Configs	string	Yes	A request to listen for data packets.
tenant	string	Yes	A packet field indicating tenant information. It corresponds to the Namespace field in Nacos.
dataId	string	Yes	A packet field indicating the configuration ID.
group	string	Yes	A packet field indicating the configuration group.
contentMD5	string	Yes	A packet field indicating the MD5 value of the configuration.

Header parameters

Name	Type	Required	Description
Long-Pulling-Timeout	string	Yes	The timeout for long polling is 30s. Enter 30,000 here.

Parameter description

• A delimiter to separate fields within a configuration: ^2 = Character.toString((char) 2, The url encoded value is %02
• A delimiter to separate configurations: ^1 = Character.toString((char) 1), The url encoded value is %01
• contentMD5: MD5(content). This is an empty string because the first local cache is empty.

Return parameters

Parameter type	Description
String	Configuration value

Error codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Client error, not found
500	Internal Server Error	Internal server error
200	OK	Normal

Example

• Request example

http://serverIp:8848/nacos/v1/cs/configs/listener

POST request body data:

Listening-Configs=dataId%02group%02contentMD5%02tenant%01

• Return example

In case of any configuration changes,

dataId%02group%02tenant%01

Otherwise, an empty string is returned.

Publish configuration

Description

It publishes configurations in Nacos.

Request Type

POST

Request URL

/nacos/v1/cs/configs

Request parameters

Name	Type	Required	Description
tenant	String	No	The tenant, corresponding to the namespace ID field of Nacos
dataId	String	Yes	Configuration ID
group	String	Yes	Configuration group
content	String	Yes	Configuration content
type	String	No	Configuration type

Response parameters

Parametertype	Description
boolean	If the publishing is successful

Error code

Error code	Description	Meaning
400	Bad Request	Syntax error in client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Example

Request example

curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' -d 'dataId=nacos.example&group=com.alibaba.nacos&content=contentTest'

Response example

true

Delete configuration

Description

It deletes configurations in Nacos.

Request Type

DELETE

Request URL

/nacos/v1/cs/configs

Request parameters

Name	Type	Required	Description
tenant	String	No	The tenant, corresponding to the namespace ID field of Nacos
dataId	String	Yes	Configuration ID
group	String	Yes	Configuration group

Response parameters

Parameter type	Description
boolean	If the deletion is successful

Error code

Error code	Description	Meaning
400	Bad Request	Syntax error in client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Example

Request example

curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.example&group=com.alibaba.nacos'

Response example

true

Query list of history configuration

Description

Query list of history configuration.

Request Type

GET

Request URL

/nacos/v1/cs/history?search=accurate

Request parameters

Name	Type	Required	Description
tenant	string	No	Tenant information. It corresponds to the Namespace ID field in Nacos.
dataId	string	Yes	Configuration ID
group	string	Yes	Configuration group
pageNo	integer	no	page number
pageSize	integer	no	page size (default:100, max:500)

Error code

Error code	Description	Meaning
400	Bad Request	Syntax error in client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Example

Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?search=accurate&dataId=nacos.example&group=com.alibaba.nacos'

Response example

{
  "totalCount": 1,
  "pageNumber": 1,
  "pagesAvailable": 1,
  "pageItems": [
    {
      "id": "203",
      "lastId": -1,
      "dataId": "nacos.example",
      "group": "com.alibaba.nacos",
      "tenant": "",
      "appName": "",
      "md5": null,
      "content": null,
      "srcIp": "0:0:0:0:0:0:0:1",
      "srcUser": null,
      "opType": "I         ",
      "createdTime": "2010-05-04T16:00:00.000+0000",
      "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
    }
  ]
}

Query the history details of the configuration

Description

Query the history details of the configuration

Request Type

GET

Request URL

/nacos/v1/cs/history

Request Parameters

Name	Type	Required	Description
nid	Integer	Yes	history config info ID
tenant	string	No	Tenant information. It corresponds to the Namespace ID field in Nacos. (Since 2.0.3)
dataId	string	Yes	Configuration ID (Since 2.0.3)
group	string	Yes	Configuration group (Since 2.0.3)

Note: From version 2.0.3, this interface need add three parameter, include tenant, dataId and group, tenant can not be provided.

Error Code

Error code	Description	Meaning
400	Bad Request	Syntax error in client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Example

Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?nid=203&tenant=&dataId=nacos.example&group=com.alibaba.nacos'

Response example

{
  "id": "203",
  "lastId": -1,
  "dataId": "nacos.example",
  "group": "com.alibaba.nacos",
  "tenant": "",
  "appName": "",
  "md5": "9f67e6977b100e00cab385a75597db58",
  "content": "contentTest",
  "srcIp": "0:0:0:0:0:0:0:1",
  "srcUser": null,
  "opType": "I         ",
  "createdTime": "2010-05-04T16:00:00.000+0000",
  "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
}

Query the previous version of the configuration

Description

Query the previous version of the configuration.(Since 1.4.0)

Request Type

GET

Request URL

/nacos/v1/cs/history/previous

Request Paramters

Name	Type	Required	Description
id	Integer	Yes	configuration unique id
tenant	string	No	Tenant information. It corresponds to the Namespace ID field in Nacos. (Since 2.0.3)
dataId	string	Yes	Configuration ID (Since 2.0.3)
group	string	Yes	Configuration group (Since 2.0.3)

Note: From version 2.0.3, this interface need add three parameter, include tenant, dataId and group, tenant can not be provided.

Error Code

Error code	Description	Meaning
400	Bad Request	Syntax error in client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Example

Request example

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history/previous?id=309135486247505920&tenant=&dataId=nacos.example&group=com.alibaba.nacos'

Response example

{
  "id": "203",
  "lastId": -1,
  "dataId": "nacos.example",
  "group": "com.alibaba.nacos",
  "tenant": "",
  "appName": "",
  "md5": "9f67e6977b100e00cab385a75597db58",
  "content": "contentTest",
  "srcIp": "0:0:0:0:0:0:0:1",
  "srcUser": null,
  "opType": "I         ",
  "createdTime": "2010-05-04T16:00:00.000+0000",
  "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
}

Service Discovery

Register instance

Description

Register an instance to service.

Request Type

POST

Request Path

/nacos/v1/ns/instance

Request Parameters

Name	Type	Required	Description
ip	String	yes	IP of instance
port	int	yes	Port of instance
namespaceId	String	no	ID of namespace
weight	double	no	Weight
enabled	boolean	no	enabled or not
healthy	boolean	no	healthy or not
metadata	String	no	extended information
clusterName	String	no	cluster name
serviceName	String	yes	service name
groupName	String	no	group name
ephemeral	boolean	no	if instance is ephemeral

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1'

Response Example

ok

Deregister instance

Description

Delete instance from service.

Request Type

DELETE

Request Path

/nacos/v1/ns/instance

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	Service name
groupName	String	no	group name
ephemeral	boolean	no	if instance is ephemeral
ip	String	yes	IP of instance
port	int	yes	Port of instance
clusterName	String	no	Cluster name
namespaceId	String	no	ID of namespace

error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1'

Response Example

ok

Modify instance

Description

Modify an instance of service.

Attension：After Nacos2.0 version, the metadata updated through this interface has a higher priority and has the ability to remember. After the instance removed, it will still exist for a period of time. If the instance is re-registered during this period, the metadata will still be Effective. You can modify the memory time through nacos.naming.clean.expired-metadata.expired-time and nacos.naming.clean.expired-metadata.interval

Request Type

PUT

Request Path

/nacos/v1/ns/instance

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	Service name
groupName	String	no	group name
ephemeral	boolean	no	if instance is ephemeral
ip	String	yes	IP of instance
port	int	yes	Port of instance
clusterName	String	no	Cluster name
namespaceId	String	no	ID of namespace
weight	double	no	Weight
enabled	boolean	no	If enabled
metadata	JSON	no	Extended information

error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1&weight=8&metadata={}'

Response Example

ok

Query instances

Description

Query instance list of service.

Request Type

GET

Request Path

/nacos/v1/ns/instance/list

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	Service name
groupName	String	no	group name
namespaceId	String	no	ID of namespace
clusters	String, splited by comma	no	Cluster name
healthyOnly	boolean	no, default value is false	Return healthy instance or not

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1'

Response Example

{
  "name": "DEFAULT_GROUP@@nacos.test.1", 
  "groupName": "DEFAULT_GROUP", 
  "clusters": "", 
  "cacheMillis": 10000, 
  "hosts": [
    {
      "instanceId": "10.10.10.10#8888#DEFAULT#DEFAULT_GROUP@@nacos.test.1", 
      "ip": "10.10.10.10", 
      "port": 8888, 
      "weight": 1, 
      "healthy": false, 
      "enabled": true, 
      "ephemeral": false, 
      "clusterName": "DEFAULT", 
      "serviceName": "DEFAULT_GROUP@@nacos.test.1", 
      "metadata": { }, 
      "instanceHeartBeatInterval": 5000, 
      "instanceIdGenerator": "simple", 
      "instanceHeartBeatTimeOut": 15000, 
      "ipDeleteTimeout": 30000
    }
  ], 
  "lastRefTime": 1528787794594, 
  "checksum": "", 
  "allIPs": false, 
  "reachProtectionThreshold": false, 
  "valid": true
}

Query instance detail

Description

Query instance details of service.

Request Type

GET

Request Path

/nacos/v1/ns/instance

Request Parameters

Name	Type	Required	Description
namespaceId	String	no	ID of namespace
serviceName	String	yes	Service name
groupName	String	no	group name
ephemeral	boolean	no	if instance is ephemeral
ip	String	yes	IP of instance
port	String	yes	Port of instance
cluster	String	no	Cluster name

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.2&ip=10.10.10.10&port=8888&cluster=DEFAULT'

Response Example

{
    "metadata": {},
    "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.2",
    "port": 8888,
    "service": "nacos.test.2",
    "healthy": false,
    "ip": "10.10.10.10",
    "clusterName": "DEFAULT",
    "weight": 1.0
}

Send instance beat

Description

Send instance beat

Request Type

PUT

Request Path

/nacos/v1/ns/instance/beat

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	service name
ip	String	yes	ip of instance
port	int	yes	port of instance
namespaceId	String	no	ID of namespace
groupName	String	no	group name
beat	String	yes	beat content

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=nacos.test.2&beat=%7b%22cluster%22%3a%22c1%22%2c%22ip%22%3a%22127.0.0.1%22%2c%22metadata%22%3a%7b%7d%2c%22port%22%3a8080%2c%22scheduled%22%3atrue%2c%22serviceName%22%3a%22jinhan0Fx4s.173TL.net%22%2c%22weight%22%3a1%7d'

Response Example

ok

Create service

Description

Create service

Request Type

POST

Request Path

/nacos/v1/ns/service

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	service name
groupName	String	no	group name
namespaceId	String	no	namespace id
protectThreshold	float	no	set value from 0 to 1, default 0
metadata	String	no	metadata of service
selector	JSON	no	visit strategy

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X POST '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

Response Example

ok

Delete service

Description

Delete a service, only permitted when instance count is 0.

Request Type

DELETE

Request Path

/nacos/v1/ns/service

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	service name
groupName	String	no	group name
namespaceId	String	no	namespace id

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

Response Example

ok

Update service

Description

Update a service

Request Type

PUT

Request Path

/nacos/v1/ns/service

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	service name
groupName	String	no	group name
namespaceId	String	no	namespace id
protectThreshold	float	no	set value from 0 to 1, default 0
metadata	String	no	metadata of service
selector	JSON	no	visit strategy

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

Response Example

ok

Query service

Description

Query a service

Request Type

GET

Request Path

/nacos/v1/ns/service

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	service name
groupName	String	no	group name
namespaceId	String	no	namespace id

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X GET '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

Response Example

{
    metadata: { },
    groupName: "DEFAULT_GROUP",
    namespaceId: "public",
    name: "nacos.test.2",
    selector: {
        type: "none"
    },
    protectThreshold: 0,
    clusters: [
        {
            healthChecker: {
                type: "TCP"
            },
            metadata: { },
            name: "c1"
        }
    ]
}

Query service list

Description

Query service list

Request Type

GET

Request Path

/nacos/v1/ns/service/list

Request Parameters

Name	Type	Required	Description
pageNo	int	yes	current page number
pageSize	int	yes	page size
groupName	String	no	group name
namespaceId	String	no	namespace id

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X GET '127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=2'

Response Example

{
    "count":148,
    "doms": [
        "nacos.test.1",
        "nacos.test.2"
    ]
}

Query system switches

Description

Query system switches

Request Type

GET

Request Path

/nacos/v1/ns/operator/switches

Request Parameters

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

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

Response Example

{
    name: "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
    masters: null,
    adWeightMap: { },
    defaultPushCacheMillis: 10000,
    clientBeatInterval: 5000,
    defaultCacheMillis: 3000,
    distroThreshold: 0.7,
    healthCheckEnabled: true,
    distroEnabled: true,
    enableStandalone: true,
    pushEnabled: true,
    checkTimes: 3,
    httpHealthParams: {
        max: 5000,
        min: 500,
        factor: 0.85
    },
    tcpHealthParams: {
        max: 5000,
        min: 1000,
        factor: 0.75
    },
    mysqlHealthParams: {
        max: 3000,
        min: 2000,
        factor: 0.65
    },
    incrementalList: [ ],
    serverStatusSynchronizationPeriodMillis: 15000,
    serviceStatusSynchronizationPeriodMillis: 5000,
    disableAddIP: false,
    sendBeatOnly: false,
    limitedUrlMap: { },
    distroServerExpiredMillis: 30000,
    pushGoVersion: "0.1.0",
    pushJavaVersion: "0.1.0",
    pushPythonVersion: "0.4.3",
    pushCVersion: "1.0.12",
    enableAuthentication: false,
    overriddenServerStatus: "UP",
    defaultInstanceEphemeral: true,
    healthCheckWhiteList: [ ],
    checksum: null
}

Update system switch

Description

Update system switch

Request Type

PUT

Request Path

/nacos/v1/ns/operator/switches

Request Parameters

Name	Type	Required	Description
entry	String	yes	switch name
value	String	yes	switch value
debug	boolean	no	if affect the local server, true means yes, false means no, default true

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&value=false&debug=true'

Response Example

ok

Query system metrics

Description

Query system metrics

Request Type

GET

Request Path

/nacos/v1/ns/operator/metrics

Request Parameters

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

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

Response Example

{
    serviceCount: 336,
    load: 0.09,
    mem: 0.46210432,
    responsibleServiceCount: 98,
    instanceCount: 4,
    cpu: 0.010242796,
    status: "UP",
    responsibleInstanceCount: 0
}

Query server list

Description

Query server list

Request Type

GET

Request Path

/nacos/v1/ns/operator/servers

Request Parameters

Name	Type	Required	Description
healthy	boolean	no	if return healthy servers only

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/servers'

Response Example

{
    servers: [
        {
            ip: "1.1.1.1",
            servePort: 8848,
            site: "unknown",
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: "1.1.1.1:8848"
        },
        {
            ip: "1.1.1.2",
            servePort: 8848,
            site: "unknown",
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: "1.1.1.2:8848"
        },
        {
            ip: "1.1.1.3",
            servePort: 8848,
            site: "unknown",
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: "1.1.1.3:8848"
        }
    ]
}

Query the leader of current cluster

Description

Query the leader of current cluster

Request Type

GET

Request Path

/nacos/v1/ns/raft/leader

Request Parameters

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X GET '127.0.0.1:8848/nacos/v1/ns/raft/leader'

Response Example

{
    leader: "{"heartbeatDueMs":2500,"ip":"1.1.1.1:8848","leaderDueMs":12853,"state":"LEADER","term":54202,"voteFor":"1.1.1.1:8848"}"
}

Update instance health status

Description

Update instance health status, only works when the cluster health checker is set to NONE.

Request Type

PUT

Request Path

/nacos/v1/ns/health/instance

Request Parameters

Name	Type	Required	Description
serviceName	String	yes	service name
groupName	String	no	group name
namespaceId	String	no	namespace id
clusterName	String	no	cluster name
ip	String	yes	ip of instance
port	int	yes	port of instance
healthy	boolean	yes	if healthy

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/health/instance?port=8848&healthy=true&ip=11.11.11.11&serviceName=nacos.test.3&namespaceId=n1'

Response Example

ok

Batch update instance metadata(Beta)

Description

Batch update instance metadata(Since 1.4)

Note: This API is a Beta API, later versions maybe modify or even delete. Please use it with caution.

Request Type

PUT

Request Path

/nacos/v1/ns/instance/metadata/batch

Request Parameters

Name	Type	Required	Description
namespaceId	String	yes	ID of namespace
serviceName	String	yes	Service name(group@@serviceName)
consistencyType	String	no	instance type (ephemeral/persist)
instances	JSON	no	The instances which need to update
metadata	JSON	yes	Metadata

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Parameter description

• consistencyType: The priority higher than param instances, if config it, the param instances will be ignored. When when value equals 'ephemeral', all the ephemeral instances in serviceName will be updated. When when value equals 'persist', all the persist instances in serviceName will be updated. When other value, no instances will be updated.
• instances: json array. To locate particular instances by (ip + port + ephemeral + cluster).

Request Example

curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]&metadata={"age":"20","name":"cocolan"}' 
or
curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&consistencyType=ephemeral&metadata={"age":"20","name":"cocolan"}'

Response Example

{"updated":["2.2.2.2:8080:unknown:xxxx-cluster:ephemeral","3.3.3.3:8080:unknown:xxxx-cluster:ephemeral"]}

Batch delete instance metadata(Beta)

Description

Batch delete instance metadata(Since 1.4)

Note: This API is a Beta API, later versions maybe modify or even delete. Please use it with caution.

Request Type

DELETE

Request Path

/nacos/v1/ns/instance/metadata/batch

Request Parameters

Name	Type	Required	Description
namespaceId	String	yes	ID of namespace
serviceName	String	yes	Service name(group@@serviceName)
consistencyType	String	no	instance type (ephemeral/persist)
instances	JSON	no	The instances which need to update
metadata	JSON	yes	Metadata

Error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Parameter description

• consistencyType: The priority higher than param instances, if config it, the param instances will be ignored. When when value equals 'ephemeral', all the ephemeral instances in serviceName will be updated. When when value equals 'persist', all the persist instances in serviceName will be updated. When other value, no instances will be updated.
• instances: json array. To locate particular instances by (ip + port + ephemeral + cluster).

Request Example

curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]&metadata={"age":"20","name":"cocolan"}' 
or
curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&consistencyType=ephemeral&metadata={"age":"20","name":"cocolan"}'

Response Example

{"updated":["2.2.2.2:8080:unknown:xxxx-cluster:ephemeral","3.3.3.3:8080:unknown:xxxx-cluster:ephemeral"]}

Namespace

Get namespace

Description

This API is used to get namespaces in Nacos.

Request Type

GET

Request Path

/nacos/v1/ns/instance

Request Parameters

None

error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X GET 'http://localhost:8848/nacos/v1/console/namespaces'

Response Example

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

Create namespace

Description

Create namespace

Request Type

POST

Request Path

/nacos/v1/console/namespaces

Request Parameters

Name	Type	Required	Description
customNamespaceId	String	yes	ID of namespace
namespaceName	String	yes	Namespace name
namespaceDesc	String	no	Namespace description

error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X POST 'http://localhost:8848/nacos/v1/console/namespaces' -d 'customNamespaceId=&namespaceName=dev&namespaceDesc='

Response Example

true

Modify namespace

Description

Update namespace

Request Type

PUT

Request Path

/nacos/v1/console/namespaces

Request Parameters

Name	Type	Required	Description
namespace	String	yes	ID of namespace
namespaceShowName	String	yes	Namespace name
namespaceDesc	String	yes	Namespace description

error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X PUT 'http://localhost:8848/nacos/v1/console/namespaces' -d 'namespace=dev&namespaceShowName=开发环境2&namespaceDesc=只用于开发2'

Response Example

true

Delete namespace

Description

It deletes namespace in Nacos.

Request Type

DELETE

Request Path

/nacos/v1/console/namespaces

Request Parameters

Name	Type	Required	Description
namespaceId	String	yes	ID of namespace

error Codes

Error code	Description	Meaning
400	Bad Request	Syntax error in the client request
403	Forbidden	No permission
404	Not Found	Not found resource
500	Internal Server Error	Internal server error
200	OK	Normal

Request Example

curl -X DELETE 'http://localhost:8848/nacos/v1/console/namespaces' -d 'namespaceId=dev'

Response Example

true