Console API

Nacos provides Console APIs for the built-in Nacos console and custom console UI implementations. These APIs expose the data and interactions needed by console pages.

If you want to disable the default Nacos console UI and use a custom UI, read Console Manual first to confirm the console entry, port, and UI switch configurations.

0. Console API Notes

0.1. Scope

Console APIs are intended for the Nacos console and custom console UI. They serve page rendering, form submission, and console interaction flows.

Business applications should use SDKs or Client API. Operations platforms, release platforms, and automation scripts should prefer Admin API or Maintainer SDK.

0.2. Unified Path Format

Nacos Console APIs use a unified path format: [/$nacos.console.contextPath]/v3/console/[module]/[subPath]....

• $nacos.console.contextPath: Root path of the console. The default value is empty, and it can be changed with the nacos.console.contextPath configuration item.
• module: Console module name, such as server, cs, ns, or core.
• subPath: Console subpath, such as state, namespace, or config. It may contain multiple path levels.

The Console APIs listed below use the default $nacos.console.contextPath. If the deployment changes $nacos.console.contextPath, update the request URL accordingly when calling the API.

The examples below also use the default Nacos Console port. If the deployment changes $nacos.console.port, update the request URL accordingly when calling the API.

0.3. Authentication

Nacos 3.X Console APIs enable authentication by default. Except for a small number of APIs marked as public, callers must provide valid identity information.

To disable Console API authentication, set nacos.core.auth.console.enabled=false and restart Nacos Console.

0.4. Swagger Documentation

Nacos 3.X Console APIs also provide Swagger-style documentation. You can view it at Nacos Swagger Console API.

1. Nacos Basic Console APIs

Basic Console APIs provide basic information about the Nacos cluster, such as cluster information and namespace information.

1.1. Get Cluster Status

Description

You can use this API to obtain basic status and switch information for the Nacos cluster, such as the version, startup mode, and whether authentication is enabled. This API does not return Nacos cluster node information.

Since

3.0.0

Request Method

GET

Authorization

Public API. No identity information is required.

Request URL

/v3/console/server/state

Request Parameters

None

Response Data

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/server/state'

• Response example

{
  "defaultMaxSize": "102400",
  "auth_system_type": "nacos",
  "auth_enabled": "false",
  "defaultMaxAggrSize": "1024",
  "maxHealthCheckFailCount": "12",
  "maxContent": "10485760",
  "console_ui_enabled": "true",
  "defaultMaxAggrCount": "10000",
  "auth_admin_request": "false",
  "defaultGroupQuota": "200",
  "config_retention_days": "30",
  "startup_mode": "standalone",
  "isHealthCheck": "true",
  "version": "3.0.0-SNAPSHOT",
  "function_mode": null,
  "isManageCapacity": "true",
  "isCapacityLimitCheck": "false",
  "datasource_platform": "",
  "notifyConnectTimeout": "100",
  "server_port": "8848",
  "notifySocketTimeout": "200",
  "defaultClusterQuota": "100000",
  "login_page_enabled": "false",
  "plugin_datasource_log_enabled": "false"
}

1.2. Get Console Announcement

Description

You can use this API to obtain the announcement that the Nacos console wants to display in the browser. The default Nacos console UI calls this API when authentication is not enabled, and the API returns a reminder that authentication is disabled for the cluster.

Since

3.0.0

Request Method

GET

Authorization

Public API. No identity information is required.

Request URL

/v3/console/server/announcement

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/server/announcement?language=zh-CN'

• Response example

{
  "code": 0,
  "message": "success",
  "data": "Authentication is not enabled for the current cluster. See the <a href=\"https://nacos.io/en/docs/v2/guide/user/auth.html\">documentation</a> to enable authentication."
}

1.3. Get Console Guide Content

Description

You can use this API to obtain guide information for the Nacos console. The default Nacos console UI calls this API when the console UI is disabled to obtain guide information. For details, see Console Manual.

Since

3.0.0

Request Method

GET

Authorization

Public API. No identity information is required.

Request URL

/v3/console/server/guide

Request Parameters

None

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/server/guide'

• Response example

{
  "code": 0,
  "message": "success",
  "data": "The Nacos open-source console is disabled on the current node. Set `nacos.console.ui.enabled=true` in `application.properties` to enable it. For details, see the console documentation."
}

1.4. Get Nacos Console Liveness Status

Description

You can use this API to obtain the liveness status of the Nacos console, that is, whether the Nacos console can normally accept and respond to requests.

Since

3.0.0

Request Method

GET

Authorization

Public API. No identity information is required.

Request URL

/v3/console/health/liveness

Request Parameters

None

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/health/liveness'

• Response example

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

1.5. Get Nacos Console Readiness Status

Description

You can use this API to obtain whether the Nacos console is in a readable state, that is, whether the Nacos console can read data.

Since

3.0.0

Request Method

GET

Authorization

Public API. No identity information is required.

Request URL

/v3/console/health/readiness

Request Parameters

None

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/health/readiness'

• Response example

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

1.6. Get Nacos Node Runtime Information

Description

You can use this API to obtain Nacos node runtime information, including node IP, node runtime status, and node metadata.

Since

3.0.0

Request Method

GET

Authorization

Nacos administrator permission is required.

Request URL

/v3/console/core/cluster/nodes

Request Parameters

None.

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/core/cluster/nodes'

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "ip": "127.0.0.1",
      "port": 8848,
      "state": "UP",
      "extendInfo": {
        "lastRefreshTime": 1733221062619,
        "raftMetaData": {
          "metaDataMap": {
            "naming_instance_metadata": {
              "leader": "127.0.0.1:7848",
              "raftGroupMember": [
                "127.0.0.1:7848"
              ],
              "term": 1
            },
            "naming_persistent_service": {
              "leader": "127.0.0.1:7848",
              "raftGroupMember": [
                "127.0.0.1:7848"
              ],
              "term": 1
            },
            "naming_persistent_service_v2": {
              "leader": "127.0.0.1:7848",
              "raftGroupMember": [
                "127.0.0.1:7848"
              ],
              "term": 1
            },
            "naming_service_metadata": {
              "leader": "127.0.0.1:7848",
              "raftGroupMember": [
                "127.0.0.1:7848"
              ],
              "term": 1
            }
          }
        },
        "raftPort": "7848",
        "readyToUpgrade": true,
        "supportGrayModel": true,
        "version": "3.0.0-SNAPSHOT"
      },
      "address": "127.0.0.1:8848",
      "failAccessCnt": 0,
      "abilities": {
        "remoteAbility": {
          "supportRemoteConnection": true,
          "grpcReportEnabled": true
        },
        "configAbility": {
          "supportRemoteMetrics": false
        },
        "namingAbility": {
          "supportJraft": true
        }
      },
      "grpcReportEnabled": true
    }
  ]
}

1.7. Get Nacos Namespace List

Description

You can use this API to obtain the namespace list of the current Nacos cluster.

Since

3.0.0

Request Method

GET

Authorization

Any valid authentication identity is required.

Because namespace is the basic isolation concept in Nacos, most data query APIs must select a namespace before querying data. Therefore, any user with a valid identity should be able to access the namespace list.

Request URL

/v3/console/core/namespace/list

Request Parameters

None

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/core/namespace/list'

• Response example

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

1.8. Get Namespace Details

Description

You can use this API to obtain the details of a specified namespace.

Since

3.0.0

Request Method

GET

Authorization

Nacos administrator permission is required.

Request URL

/v3/console/core/namespace

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/core/namespace?namespaceId=public'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "namespace": "public",
    "namespaceShowName": "public",
    "namespaceDesc": "Default Namespace",
    "quota": 200,
    "configCount": 0,
    "type": 0
  }
}

1.9. Create Namespace

Description

You can use this API to create a namespace.

Since

3.0.0

Request Method

POST

Authorization

Nacos administrator permission is required.

Request URL

/v3/console/core/namespace

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X POST 'http://127.0.0.1:8080/v3/console/core/namespace' -d 'namespaceName=test&namespaceDesc=test'

• Response example

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

1.10. Update Namespace

Description

You can use this API to update namespace information. The namespace ID cannot be updated; only the name and description can be updated.

Since

3.0.0

Request Method

PUT

Authorization

Nacos administrator permission is required.

Request URL

/v3/console/core/namespace

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8080/v3/console/core/namespace' -d 'namespaceId=test&namespaceName=test&namespaceDesc=test'

• Response example

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

1.11. Delete Namespace

Description

You can use this API to delete a namespace. The default public namespace cannot be deleted.

Since

3.0.0

Request Method

DELETE

Authorization

Nacos administrator permission is required.

Request URL

/v3/console/core/namespace

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X DELETE 'http://127.0.0.1:8080/v3/console/core/namespace?namespaceId=test'

• Response example

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

1.12. Check Whether a Namespace Exists

Description

You can use this API to check whether a namespace ID exists. The default console calls this API before creating a namespace to confirm whether the custom namespace ID already exists and avoid conflicts.

Since

3.0.0

Request Method

GET

Authorization

Any valid authentication identity is required.

Request URL

/v3/console/core/namespace/exist

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/core/namespace/exist?customNamespaceId=test'

• Response example

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

1.13. Get Plugin Details

Description

You can use this API to obtain details about a specified plugin by type and name.

Since

3.2.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/plugin

Request Parameters

Response Data

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/plugin?pluginType=auth&pluginName=nacos-default-auth-plugin'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "name": "nacos-default-auth-plugin",
    "type": "auth",
    "enabled": true,
    "config": {}
  }
}

1.14. Query Plugin Availability on Cluster Nodes

Description

You can use this API to obtain the availability of a specified plugin on each cluster node.

Since

3.2.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/plugin/availability

Request Parameters

Response Data

The returned data is a Map<node address, availability>. The key is the Nacos node address, such as 127.0.0.1:8848, and the value indicates whether the plugin is available on that node.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/plugin/availability?pluginType=auth&pluginName=nacos-default-auth-plugin'

• Response example

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

1.15. Update Plugin Configuration

Description

You can use this API to update plugin configuration. You must provide the plugin type, name, and configuration content.

Since

3.2.0

Request Method

PUT

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/plugin/config

Request Parameters

Response Data

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8080/v3/console/plugin/config' \
  -d 'pluginType=auth' \
  -d 'pluginName=nacos-default-auth-plugin' \
  -d 'config={}'

• Response example

{
  "code": 0,
  "message": "success",
  "data": "Plugin configuration updated successfully"
}

1.16. Get Plugin List

Description

You can use this API to obtain the plugin list. You can filter the list by plugin type.

Since

3.2.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/plugin/list

Request Parameters

Response Data

The returned data is an array of plugin information. Each item contains the plugin name, type, enabled status, and other fields.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/plugin/list?pluginType=auth'

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "name": "nacos-default-auth-plugin",
      "type": "auth",
      "enabled": true
    }
  ]
}

1.17. Enable or Disable a Plugin

Description

You can use this API to update whether a plugin is enabled or disabled.

Since

3.2.0

Request Method

PUT

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/plugin/status

Request Parameters

Response Data

Examples

• Request example

curl -X PUT 'http://127.0.0.1:8080/v3/console/plugin/status' \
  -d 'pluginType=auth' \
  -d 'pluginName=nacos-default-auth-plugin' \
  -d 'enabled=True'

• Response example

{
  "code": 0,
  "message": "success",
  "data": "Plugin status updated successfully"
}

2. Configuration Management

2.1. Get Configuration Details

Description

You can use this API to obtain the details of a specified configuration.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/config

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/cs/config?dataId=test&groupName=test'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "appName": "",
    "configTags": null,
    "content": "test",
    "createIp": "127.0.0.1",
    "createTime": 1741681316620,
    "createUser": "nacos",
    "dataId": "test",
    "desc": null,
    "encryptedDataKey": "",
    "groupName": "test",
    "id": "873472517803610112",
    "md5": "098f6bcd4621d373cade4e832627b4f6",
    "modifyTime": 1741681316620,
    "namespaceId": "public",
    "type": "text"
  }
}

2.2. Publish Configuration

Description

You can use this API to create a new configuration or update an existing configuration.

Since

3.0.0

Request Method

POST

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/cs/config

Request Parameters

• When the configuration already exists with the same dataId and groupName, calling this API again updates the configuration.
• When publishing a configuration, if the request Header contains betaIps, the configuration is marked as a BETA configuration. Before the BETA release is stopped or fully published, the console UI must handle it specially.

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X POST 'http://127.0.0.1:8080/v3/console/cs/config' -d 'dataId=test&groupName=test&namespaceId=public&content=test'

• Response example

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

2.3. Delete Configuration

Description

You can use this API to delete a specified configuration.

Since

3.0.0

Request Method

DELETE

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/cs/config

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X DELETE 'http://127.0.0.1:8080/v3/console/cs/config?dataId=test&groupName=test'

• Response example

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

2.4. Batch Delete Configurations

Description

You can use this API to batch delete specified configurations.

Since

3.0.0

Request Method

DELETE

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/cs/config/batchDelete

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X DELETE 'http://127.0.0.1:8080/v3/console/cs/config/batchDelete?ids=838025461287096320,838025489170829312'

• Response example

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

2.5. Query Configuration List

Description

You can use this API to query the configuration list in a specified namespace.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/config/list

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/cs/config/list?dataId=&groupName=&appName=&configTags=&pageNo=1&pageSize=10&namespaceId=&type=&search=blur'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "pageItems": [
      {
        "appName": "",
        "createTime": 0,
        "dataId": "aaa",
        "groupName": "DEFAULT_GROUP",
        "id": "873471898128748544",
        "md5": null,
        "modifyTime": 0,
        "namespaceId": "public",
        "type": "text"
      },
      {
        "appName": "",
        "createTime": 0,
        "dataId": "bbb",
        "groupName": "DEFAULT_GROUP",
        "id": "873473460813172736",
        "md5": null,
        "modifyTime": 0,
        "namespaceId": "public",
        "type": "text"
      }
    ],
    "pageNumber": 1,
    "pagesAvailable": 1,
    "totalCount": 2
  }
}

2.6. Query Configurations by Content

Description

You can use this API to query the list of configurations that match configuration content.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/config/searchDetail

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/cs/config/searchDetail?dataId=&groupName=&appName=&configTags=&pageNo=1&pageSize=10&namespaceId=&type=&search=blur&configDetail=*11*'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "pageItems": [
      {
        "appName": "",
        "createTime": 0,
        "dataId": "111",
        "groupName": "DEFAULT_GROUP",
        "id": "873475812546842624",
        "md5": null,
        "modifyTime": 0,
        "namespaceId": "public",
        "type": "text"
      }
    ],
    "pageNumber": 1,
    "pagesAvailable": 1,
    "totalCount": 1
  }
}

2.7. Query Configuration Listener List

Description

You can use this API to query the listener list of a specified configuration.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/config/listener

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/cs/config/listener?dataId=test&groupName=test'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "listenersStatus": {
      "127.0.0.1": "32cacc65accfdab47954de3fc781e938"
    },
    "queryType": "config"
  }
}

2.8. Query Configurations Subscribed by a Subscriber IP

Description

You can use this API to query which configurations are subscribed to by a specified subscriber IP.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/config/listener/ip

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET 'http://127.0.0.1:8080/v3/console/cs/config/listener/ip?ip=127.0.0.1'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "listenersStatus": {
      "qtc-user.yaml+DEFAULT_GROUP+public": "32cacc65accfdab47954de3fc781e938"
    },
    "queryType": "ip"
  }
}

2.9. Export Configurations

Description

You can use this API to export selected or queried configurations as a ZIP file for backup or import into another Nacos cluster.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/config/export2

Request Parameters

It is recommended to use either ids or the dataId + groupName combination. Choose only one method and pass an empty string for the other type. Otherwise, the exported file may be empty.

Response Data

When export succeeds, the response is a byte-array file. The file is returned in attachment mode. When export fails, the response body follows the Nacos Open API unified response format.

Examples

• Request example

curl -X GET "http://127.0.0.1:8080/v3/console/cs/config/export2?dataId=&groupId=&ids=" --output ~/test.zip

• Response example

unzip ~/test.zip
> Archive:  /path/to/test.zip
>   inflating: DEFAULT_GROUP/111
>   inflating: DEFAULT_GROUP/qtc-user.yaml
>   inflating: .metadata.yml

2.10. Import Configurations

Description

You can use this API to import a ZIP file exported from Nacos into a specified Nacos namespace.

Since

3.0.0

Request Method

POST

Request body type: multipart/form-data.

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/cs/config/import

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -vX POST "http://127.0.0.1:8080/v3/console/cs/config/import" -F "file=@/path/to/test.zip" -F "namespaceId=test"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "succCount": 2,
    "skipCount": 0
  }
}

2.11. Clone Configurations

Description

You can use this API to clone selected or queried configurations to another namespace.

Since

3.0.0

Request Method

POST

Request body type: application/json, with a configuration list array.

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/cs/config/clone

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -H "Content-Type: application/json" -X POST "http://127.0.0.1:8080/v3/console/cs/config/clone?targetNamespaceId=public&policy=ABORT" -d "[{\"cfgId\":838029534438625280,\"dataId\":\"111\",\"group\":\"DEFAULT_GROUP\"},{\"cfgId\":838033747294031872,\"dataId\":\"qtc-user.yaml\",\"group\":\"DEFAULT_GROUP\"}]"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "succCount": 2,
    "skipCount": 0
  }
}

2.12. Stop Configuration BETA Release

Description

You can use this API to stop a configuration from the BETA publishing state, that is, roll back the configuration BETA publishing state.

Since

3.0.0

Request Method

DELETE

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/cs/config/beta

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X DELETE "http://127.0.0.1:8080/v3/console/cs/config/beta?dataId=test&groupName=DEFAULT_GROUP"

• Response example

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

2.13. Query Configuration BETA Release Status

Description

You can use this API to query the BETA publishing status of a configuration.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/config/beta

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl "http://127.0.0.1:8080/v3/console/cs/config/beta?dataId=111&groupName=DEFAULT_GROUP"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "appName": "",
    "configTags": null,
    "content": "bbb11xxccc",
    "createIp": null,
    "createTime": 0,
    "createUser": "nacos",
    "dataId": "111",
    "desc": null,
    "encryptedDataKey": null,
    "grayName": "beta",
    "grayRule": "{\"type\":\"beta\",\"version\":\"1.0.0\",\"expr\":\"1.1.1.1\",\"priority\":2147483647}",
    "groupName": "DEFAULT_GROUP",
    "id": "873481464488923136",
    "md5": "2f080e5e21ba12bb8ca6894ac0fc5862",
    "modifyTime": 1741683449619,
    "namespaceId": "public",
    "type": null
  }
}

2.14. Query Configuration Publishing History

Description

You can use this API to query the publishing history of a configuration.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/history/list

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl "http://127.0.0.1:8080/v3/console/cs/history/list?pageNo=1&pageSize=10&dataId=111&groupName=DEFAULT_GROUP"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "pageItems": [
      {
        "appName": "",
        "createTime": 1272988800000,
        "dataId": "111",
        "groupName": "DEFAULT_GROUP",
        "id": "18",
        "md5": null,
        "modifyTime": 1741683760489,
        "namespaceId": "public",
        "opType": "D         ",
        "publishType": "gray",
        "srcIp": "127.0.0.1",
        "srcUser": "nacos",
        "type": null
      },
      {
        "appName": "",
        "createTime": 1272988800000,
        "dataId": "111",
        "groupName": "DEFAULT_GROUP",
        "id": "17",
        "md5": null,
        "modifyTime": 1741683449619,
        "namespaceId": "public",
        "opType": "I         ",
        "publishType": "gray",
        "srcIp": "0:0:0:0:0:0:0:1",
        "srcUser": "nacos",
        "type": null
      },
      {
        "appName": "",
        "createTime": 1272988800000,
        "dataId": "111",
        "groupName": "DEFAULT_GROUP",
        "id": "7",
        "md5": null,
        "modifyTime": 1741682102157,
        "namespaceId": "public",
        "opType": "I         ",
        "publishType": "formal",
        "srcIp": "0:0:0:0:0:0:0:1",
        "srcUser": "nacos",
        "type": null
      }
    ],
    "pageNumber": 1,
    "pagesAvailable": 1,
    "totalCount": 3
  }
}

2.15. Query a Configuration History Change Record

Description

You can use this API to query a specific history change record of a configuration.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/history

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl "http://127.0.0.1:8080/v3/console/cs/history?dataId=111&groupName=DEFAULT_GROUP&nid=7"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "appName": "",
    "content": "bbb11xx",
    "createTime": 1272988800000,
    "dataId": "111",
    "encryptedDataKey": "",
    "extInfo": "{\"src_user\":\"nacos\",\"type\":\"text\",\"c_desc\":\"111\"}",
    "grayName": "",
    "groupName": "DEFAULT_GROUP",
    "id": "7",
    "md5": "7d37afdb0b04d958d529bcb6de44fa71",
    "modifyTime": 1741682102157,
    "namespaceId": "public",
    "opType": "I         ",
    "publishType": "formal",
    "srcIp": "0:0:0:0:0:0:0:1",
    "srcUser": "nacos",
    "type": null
  }
}

2.16. Query Previous Change History Before the Latest Configuration State

Description

You can use this API to query the previous change history before the latest state of a configuration.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/history/previous

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl "http://127.0.0.1:8080/v3/console/cs/history/previous?id=838029534438625280&dataId=111&groupName=DEFAULT_GROUP"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "appName": "",
    "content": "bbb11xx",
    "createTime": 1272988800000,
    "dataId": "111",
    "encryptedDataKey": "",
    "extInfo": "{\"src_user\":\"nacos\",\"type\":\"text\",\"c_desc\":\"111\"}",
    "grayName": "",
    "groupName": "DEFAULT_GROUP",
    "id": "7",
    "md5": "7d37afdb0b04d958d529bcb6de44fa71",
    "modifyTime": 1741682102157,
    "namespaceId": "public",
    "opType": "I         ",
    "publishType": "formal",
    "srcIp": "0:0:0:0:0:0:0:1",
    "srcUser": "nacos",
    "type": null
  }
}

2.17. Query Configuration List in a Namespace

Description

You can use this API to query the configuration list in a namespace. It returns only dataId and groupName for the drop-down selection in the configuration history UI.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/cs/history/configs

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

All other fields are unused.

Examples

• Request example

curl "http://127.0.0.1:8080/v3/console/cs/history/configs?namespaceId=public"

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "appName": "",
      "createTime": 0,
      "dataId": "111",
      "groupName": "DEFAULT_GROUP",
      "id": "0",
      "md5": null,
      "modifyTime": 1741682102161,
      "namespaceId": "public",
      "type": "text"
    },
    {
      "appName": "",
      "createTime": 0,
      "dataId": "qtc-user.yaml",
      "groupName": "DEFAULT_GROUP",
      "id": "0",
      "md5": null,
      "modifyTime": 1741682291519,
      "namespaceId": "public",
      "type": "text"
    }
  ]
}

3. Service Management

3.1. Create Service

Description

You can use this API to create an empty service.

Since

3.0.0

Request Method

POST

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/ns/service

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X POST "http://127.0.0.1:8080/v3/console/ns/service" -d "serviceName=test&groupName=DEFAULT_GROUP&namespaceId=public"

• Response example

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

3.2. Delete Service

Description

You can use this API to delete a service.

Since

3.0.0

Request Method

DELETE

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/ns/service

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X DELETE "http://127.0.0.1:8080/v3/console/ns/service?serviceName=test&groupName=DEFAULT_GROUP&namespaceId=public"

• Response example

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

3.3. Update Service Metadata

Description

You can use this API to update service metadata. Only service metadata, such as metadata and selector, can be updated. The service serviceName, groupName, and namespaceId cannot be updated.

Since

3.0.0

Request Method

PUT

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/ns/service

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X PUT "http://127.0.0.1:8080/v3/console/ns/service" -d "serviceName=test&groupName=DEFAULT_GROUP&namespaceId=public&protectThreshold=0"

• Response example

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

3.4. Get Supported Service Selector Type List

Description

You can use this API to obtain the list of supported service selector types. The console UI uses it to render the selector type drop-down when creating or updating services.

Since

3.0.0

Request Method

GET

Authorization

Any valid authentication identity is required.

Request URL

/v3/console/ns/service/selector/types

Request Parameters

None

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET "http://127.0.0.1:8080/v3/console/ns/service/selector/types"

• Response example

{
  "code": 0,
  "message": "success",
  "data": [
    "label",
    "none"
  ]
}

3.5. Query Service List

Description

You can use this API to query the service list in a specified namespace.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/ns/service/list

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET "http://127.0.0.1:8080/v3/console/ns/service/list?pageNo=1&pageSize=10&namespaceId=public"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "pageItems": [
      {
        "clusterCount": 1,
        "groupName": "DEFAULT_GROUP",
        "healthyInstanceCount": 1,
        "ipCount": 1,
        "name": "com.test.SyncCallbackService",
        "triggerFlag": "false"
      },
      {
        "clusterCount": 1,
        "groupName": "DEFAULT_GROUP",
        "healthyInstanceCount": 0,
        "ipCount": 1,
        "name": "test",
        "triggerFlag": "true"
      }
    ],
    "pageNumber": 1,
    "pagesAvailable": 1,
    "totalCount": 2
  }
}

3.6. Query Service Subscriber List

Description

You can use this API to query the subscriber list of a specified service.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/ns/service/subscribers

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET "http://127.0.0.1:8080/v3/console/ns/service/subscribers?pageNo=1&pageSize=10&serviceName=test&groupName=DEFAULT_GROUP"

• Response example

{
  "code": 0,
  "data": {
    "pageItems": [
      {
        "address": "127.0.0.1:0",
        "agent": "Nacos-Java-Client:v3.0.0-BETA",
        "appName": "unknown",
        "groupName": "DEFAULT_GROUP",
        "ip": "127.0.0.1",
        "namespaceId": "public",
        "port": 0,
        "serviceName": "test"
      }
    ],
    "pageNumber": 1,
    "pagesAvailable": 1,
    "totalCount": 1
  },
  "message": "success"
}

3.7. Query Service Details

Description

You can use this API to query the details of a specified service.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/ns/service

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X GET "http://127.0.0.1:8080/v3/console/ns/service?serviceName=test"

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "clusterMap": {
      "DEFAULT": {
        "clusterName": "DEFAULT",
        "healthChecker": {
          "type": "TCP"
        },
        "healthyCheckPort": 80,
        "hosts": null,
        "metadata": {},
        "useInstancePortForCheck": true
      }
    },
    "ephemeral": false,
    "groupName": "DEFAULT_GROUP",
    "metadata": {},
    "namespaceId": "public",
    "protectThreshold": 0.0,
    "selector": {
      "contextType": "NONE",
      "type": "none"
    },
    "serviceName": "test"
  }
}

3.8. Update Service Cluster Metadata

Description

You can use this API to update metadata for a specified service cluster.

Since

3.0.0

Request Method

PUT

Authorization

A user identity with the corresponding namespace write permission is required.

Request URL

/v3/console/ns/service/cluster

Request Parameters

The healthChecker parameter is a JSON string for the health checker. Three health checkers are currently supported:

1. None: no health check, {"type":"NONE"}
2. TCP: TCP port check, {"type":"TCP"}
3. HTTP: HTTP port check, {"type":"HTTP","path":"/liveness","headers":"health"}. path is the HTTP URI, and headers are HTTP request headers.

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.

Examples

• Request example

curl -X PUT "http://127.0.0.1:8080/v3/console/ns/service/cluster" -d "serviceName=test&clusterName=DEFAULT&checkPort=80&useInstancePort4Check=true&healthChecker={\"type\":\"none\"}"

• Response example

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

3.9. Query Service Instance List

Description

You can use this API to query the instance list of a specified service.

Since

3.0.0

Request Method

GET

Authorization

A user identity with the corresponding namespace read permission is required.

Request URL

/v3/console/ns/instance/list

Request Parameters

Response Data

The response body follows the Nacos Open API unified response format. The table below describes only the response parameters in the data field.