控制台API

Nacos 提供了若干开放的控制台API，当您有自定义开发Nacos对应的控制台UI需求时，您可以通过这些API，获取Nacos Server节点中的数据，从而实现自定义的Nacos控制台UI界面。

同时配合关闭Nacos 默认控制台UI来使用自定义UI，相关详情请参考控制台手册-关闭默认控制台

0. 控制台API 相关说明

0.1. 统一路径格式

Nacos的控制台 API，使用统一的Path格式进行的规范。格式为[/$nacos.console.contextPath]/v3/console/[module]/[subPath]..., 其中

$nacos.console.contextPath：控制台的根路径，默认为“，可以通过nacos.console.contextPath配置项进行修改。
module：控制台的模块名称，例如server、cs、ns、core等。
subPath：控制台的子路径，例如state、namespace、config等，可能有多层子路径。

下列列出的控制台API，采用默认$nacos.console.contextPath的情况进行展示，若已修改部署环境中的$nacos.console.contextPath 配置项，请自行修改调用API时的请求URL。

同时下列列出的控制台API样例中，均采用默认Nacos Console的端口进行展示，若已修改部署环境中的$nacos.console.port 配置项，请自行修改调用API时的请求URL。

0.2. 鉴权认证

Nacos 3.X 的控制台 API默认启用鉴权认证，除少量被标记为公开接口的API外，请在调用API时，携带正确的身份信息，否则请求将会被拦截。

若想要关闭鉴权，请设置nacos.core.auth.console.enabled=false，然后重启Nacos 控制台。

0.3. Swagger 类型文档

Nacos 3.X 的控制台 API 也提供了Swagger风格的文档，您可以通过访问Nacos Swagger控制台 API查看。

1. Nacos 基础控制台API

基础控制台API提供了Nacos 集群的基础信息，例如集群信息、命名空间信息等。

1.1. 获取集群状态信息

接口描述

通过该接口，可以获取到Nacos 集群的基础状态和开关信息，例如：版本号，运行模式，鉴权是否开启等；该接口不会返回Nacos 集群的节点信息。

请求方式

GET

鉴权状态

公开接口，无需身份信息。

请求URL

/v3/console/server/state

请求参数

无

返回数据

参数名	参数类型	描述
version	`string`	Nacos集群的版本号，例如`3.0.0`
startup_mode	`string`	Nacos集群的模式，例如`standalone`、`cluster`
server_port	`integer`	Nacos集群的主端口，例如`8848`
function_mode	`string`	Nacos集群的功能模式，例如`config`、`naming`、`all`, 若为`null`时，相当于`all`
datasource_platform	`string`	Nacos集群的数据源类型，例如`mysql`、`derby`等，若为“时，说明使用默认数据源类型
console_ui_enabled	`boolean`	Nacos控制台UI是否启用
auth_enabled	`boolean`	Nacos是否启用鉴权
auth_admin_request	`boolean`	Nacos是否需要初始化admin用户`nacos`
auth_system_type	`string`	Nacos鉴权的插件类型，例如`nacos`等，若为“时，说明使用默认鉴权系统类型
login_page_enabled	`boolean`	Nacos控制台是否启用登录页
plugin_datasource_log_enabled	`boolean`	Nacos是否启用打印数据源访问Debug日志
config_retention_days	`integer`	Nacos集群的配置历史数据保留天数，单位为天
isManageCapacity	`boolean`	Nacos是否启用配置容量限制检查，默认为`true`，开启时仅会统计当前配置的使用量，在超过限额时不会拒绝请求。
isCapacityLimitCheck	`boolean`	Nacos是否启用配置容量限制检查，默认为`false`，开启后当配置容量超出限额时，会拒绝配置的变更请求。
defaultMaxSize	`integer`	Nacos集群的配置文件大小限制，单位为Byte，默认为`102400`，即100KB。
defaultGroupQuota	`integer`	Nacos集群的单个分组（GroupName）下的配置文件数量限额，默认为`200`。
defaultClusterQuota	`integer`	Nacos集群的整个集群配置文件数量限额，默认为`100000`。
isHealthCheck	`boolean`	Nacos是否启用naming模块健康检查，默认为`true`，开启后当注册到nacos上的服务实例出现异常时，Nacos会主动剔除该服务端节点。
~~maxContent~~	`integer`	已废弃，请使用`defaultMaxSize`。
~~defaultMaxAggrSize~~	`integer`	未实际使用，已废弃
~~defaultMaxAggrCount~~	`integer`	未实际使用，已废弃

示例

请求示例

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

返回示例

{
  "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. 获取控制台公告信息

接口描述

通过该接口，可以获取到Nacos 控制台希望在浏览器中显示的公告信息。Nacos默认控制台UI会在未开启鉴权时调用此接口，返回集群未开启鉴权的提示。

请求方式

GET

鉴权状态

公开接口，无需身份信息。

请求URL

/v3/console/server/announcement

请求参数

参数名	类型	必填	参数描述
`language`	`string`	否	访问的语言i18n值，默认为`zh-CN`，目前仅支持`zh-CN`和`en-US`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	控制台公告内容

示例

请求示例

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

返回示例

{
  "code": 0,
  "message": "success",
  "data": "当前集群没有开启鉴权，请参考<a href=\"https://nacos.io/zh-cn/docs/v2/guide/user/auth.html\">文档</a>开启鉴权~"
}

1.3. 获取控制台引导内容

接口描述

通过该接口，可以获取Nacos控制台的引导信息。Nacos默认控制台UI会在关闭Nacos控制台UI时调用，以获取引导信息，相关详情请参考控制台手册-关闭默认控制台。

请求方式

GET

鉴权状态

公开接口，无需身份信息。

请求URL

/v3/console/server/guide

请求参数

无

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	控制台引导内容

示例

请求示例

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

返回示例

{
  "code": 0,
  "message": "success",
  "data": "当前节点已关闭Nacos开源控制台使用，请修改application.properties中的nacos.console.ui.enabled参数为true打开开源控制台使用，详情查看<a href=\"https://nacos.io/zh-cn/docs/v2/guide/admin/console-guide.html\">文档</a>中关于<code>关闭默认控制台部分</code>。"
}

1.4. 获取Nacos控制台的存活状态

接口描述

通过该接口，可以获取Nacos控制台的存活状态，Nacos控制台是否可正常接受和响应请求。

请求方式

GET

鉴权状态

公开接口，无需身份信息。

请求URL

/v3/console/health/liveness

请求参数

无

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	固定为`ok`

示例

请求示例

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

返回示例

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

1.5. 获取Nacos控制台的可读状态

接口描述

通过该接口，可以获取Nacos控制台的是否处于可读取状态，即Nacos控制台是否可以读取到数据。

请求方式

GET

鉴权状态

公开接口，无需身份信息。

请求URL

/v3/console/health/readiness

请求参数

无

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	若为可读状态时，固定为`ok`，否则为不可读的模块即对应原因信息

示例

请求示例

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

返回示例

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

1.6. 获取Nacos节点运行信息

接口描述

通过该接口，可以获取Nacos节点运行信息，包括节点ip，节点运行状态，节点元数据等。

请求方式

GET

鉴权状态

需要Nacos 管理员用户权限。

请求URL

/v3/console/core/cluster/nodes

请求参数

无。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述

示例

请求示例

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

返回示例

{
  "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. 获取Nacos命名空间列表

接口描述

通过该接口，可以获取当前Nacos集群的命名空间列表。

请求方式

GET

鉴权状态

任意有效鉴权身份信息。

由于命名空间是Nacos的基础隔离概念，因此大多数数据查询的接口都需要选择某个命名空间才能进行查询。因此，获取命名空间列表的能力应该是任意有效身份信息用户均可访问。

请求URL

/v3/console/core/namespace/list

请求参数

无

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`namespace`	`string`	命名空间id
`namespaceShowName`	`string`	命名空间名称
`namespaceDesc`	`string`	命名空间描述
`configCount`	`integer`	命名空间下的配置个数
`quota`	`integer`	命名空间的配置个数配额，需开启配置配额功能才会实际生效，默认不开启，仅做预留字段。
`type`	`integer`	命名空间的类型，预留字段，目前为`0`时为默认命名空间、`2`时为自定义创建的命名空间。

示例

请求示例

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

返回示例

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

1.8. 获取命名空间详情

接口描述

通过该接口，可以获取指定命名空间的详情。

请求方式

GET

鉴权状态

需要Nacos 管理员用户权限。

请求URL

/v3/console/core/namespace

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	是	命名空间id。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`namespace`	`string`	命名空间id
`namespaceShowName`	`string`	命名空间名称
`namespaceDesc`	`string`	命名空间描述
`configCount`	`integer`	命名空间下的配置个数
`quota`	`integer`	命名空间的配置个数配额，需开启配置配额功能才会实际生效，默认不开启，仅做预留字段。
`type`	`integer`	命名空间的类型，预留字段，目前为`0`时为默认命名空间、`2`时为自定义创建的命名空间。

示例

请求示例

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

返回示例

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

1.9. 创建新命名空间

接口描述

通过该接口，可以创建新的命名空间。

请求方式

POST

鉴权状态

需要Nacos 管理员用户权限。

请求URL

/v3/console/core/namespace

请求参数

参数名	类型	必填	参数描述
`customNamespaceId`	`string`	否	命名空间id，未填入时将会使用UUID生成ID。
`namespaceName`	`string`	是	命名空间名称。
`namespaceDesc`	`string`	否	命名空间描述。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`boolean`	创建命名空间是否成功。

示例

请求示例

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

返回示例

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

1.10. 更新命名空间

接口描述

通过该接口，可以更新命名空间的信息，无法更新命名空间ID，仅能更新命名空间的名称和描述。

请求方式

PUT

鉴权状态

需要Nacos 管理员用户权限。

请求URL

/v3/console/core/namespace

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	是	命名空间ID
`namespaceName`	`string`	是	命名空间名称。
`namespaceDesc`	`string`	否	命名空间描述。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`boolean`	更新命名空间是否成功。

示例

请求示例

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

返回示例

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

1.11. 删除命名空间

接口描述

通过该接口，可以删除命名空间。默认命名空间public无法被删除。

请求方式

DELETE

鉴权状态

需要Nacos 管理员用户权限。

请求URL

/v3/console/core/namespace

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	是	命名空间ID。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`boolean`	删除命名空间是否成功。

示例

请求示例

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

返回示例

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

1.12. 检查命名空间是否存在

接口描述

通过该接口，可以检查命名空间ID是否存在。默认控制台ID将在创建命名空间前调用，确认自定义的命名空间ID是否已经存在，以防冲突。

请求方式

GET

鉴权状态

任意有效鉴权身份信息。

请求URL

/v3/console/core/namespace/exist

请求参数

参数名	类型	必填	参数描述
`customNamespaceId`	`string`	是	命名空间ID，传入空字符串时认为是需要自动生成的UUID。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`boolean`	命名空间是否存在，存在是为`true`，否则为`false`

示例

请求示例

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

返回示例

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

1.13. 获取插件详情

接口描述

通过该接口，可以按类型和名称获取指定插件的详情信息。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/plugin

请求参数

参数名	类型	必填	参数描述
`pluginType`	`string`	是	插件类型，如 `auth`（鉴权）、`control`（控制）、`datasource`（数据源）等。
`pluginName`	`string`	是	插件名称，如 `nacos-default-auth-plugin`。

返回数据

参数名	参数类型	描述
data.pluginId	`string`	插件唯一标识。
data.pluginType	`string`	插件类型。
data.pluginName	`string`	插件名称。
data.enabled	`boolean`	当前是否已启用。
data.critical	`boolean`	是否为关键插件（关键插件不可被禁用）。
data.configurable	`boolean`	是否支持控制台动态配置。
data.config	`object`	插件当前配置项。
data.configDefinitions	`array`	插件配置项定义列表，用于渲染配置表单。

示例

请求示例

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

返回示例

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

1.14. 查询插件在集群节点上的可用性

接口描述

通过该接口，可以获取指定插件在各集群节点上的可用情况。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/plugin/availability

请求参数

参数名	类型	必填	参数描述
`pluginType`	`string`	是	插件类型，如 `auth`、`control`、`datasource` 等。
`pluginName`	`string`	是	插件名称。

返回数据

返回 data 为 Map<节点地址, 是否可用>，键为 Nacos 节点地址（如 127.0.0.1:8848），值为该节点上该插件是否可用。

示例

请求示例

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

返回示例

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

1.15. 更新插件配置

接口描述

通过该接口，可以更新插件的配置。需要提供插件类型、名称及配置内容。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/plugin/config

请求参数

参数名	类型	必填	参数描述
`pluginType`	`string`	是	插件类型。
`pluginName`	`string`	是	插件名称。
`config`	`string`	否	插件配置内容，JSON 对象，具体字段由插件定义。

返回数据

参数名	参数类型	描述
data	`string`	操作结果描述信息。

示例

请求示例

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

返回示例

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

1.16. 获取插件列表

接口描述

通过该接口，可以获取插件列表，可按插件类型筛选。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/plugin/list

请求参数

参数名	类型	必填	参数描述
`pluginType`	`string`	否	插件类型；不传则返回所有类型的插件列表。

返回数据

返回 data 为插件信息数组，每项包含插件名称、类型、是否启用等。

示例

请求示例

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

返回示例

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

1.17. 启用或禁用插件

接口描述

通过该接口，可以更新插件的启用状态（启用或禁用）。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/plugin/status

请求参数

参数名	类型	必填	参数描述
`pluginType`	`string`	是	插件类型。
`pluginName`	`string`	是	插件名称。
`enabled`	`boolean`	是	是否启用，`true` 启用、`false` 禁用。
`localOnly`	`boolean`	否	是否仅更新本地节点插件状态。

返回数据

参数名	参数类型	描述
data	`string`	操作结果描述信息。

示例

请求示例

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'

返回示例

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

2. 配置管理

2.1. 获取配置详情

接口描述

通过该接口，可以获取指定配置的详情。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/config

请求参数

参数名	类型	必填	参数描述
`dataId`	`string`	是	配置ID。
`groupName`	`string`	是	配置分组。
`namespaceId`	`string`	否	命名空间ID，默认值为`public`

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`id`	`string`	配置在存储系统中的ID，一般为Long类型的字符串。
`dataId`	`string`	配置ID。
`groupName`	`string`	配置分组。
`namespaceId`	`string`	命名空间ID。
`content`	`string`	配置内容。
`desc`	`string`	配置描述。
`md5`	`string`	配置内容的MD5值。
`configTags`	`string`	配置的标签。
`encryptedDataKey`	`string`	加密配置内容的密钥，使用配置加密插件时存在。
`appName`	`string`	配置所属的应用名称。
`type`	`string`	配置类型。
`createTime`	`integer`	配置创建时间。
`modifyTime`	`integer`	配置修改时间。
`createUser`	`string`	配置创建人。
`createIp`	`string`	配置创建IP。

示例

请求示例

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

返回示例

{
  "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. 发布配置

接口描述

通过该接口，可以创建新的配置或更新已有配置。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/cs/config

请求参数

参数名	类型	必填	参数描述
`dataId`	`string`	是	配置ID。
`groupName`	`string`	是	配置分组。
`namespaceId`	`string`	否	命名空间ID，默认值为`public`
`content`	`string`	是	配置内容。
`desc`	`string`	否	配置描述。
`type`	`string`	否	配置类型，默认值为`text`。
`configTags`	`string`	否	配置标签，多个标签之间用英文逗号分隔。
`appName`	`string`	否	配置所属应用名称，主要用于标记配置所使用的应用。

当配置已存在(dataId,groupName相同)时，再次调用此接口将会对此配置进行更新
同时更新配置时，若请求Header中存在betaIps，则会将配置标记为BETA配置，在终止BETA或完全发布配置之前，控制台UI需要进行特殊处理。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`boolean`	创建配置是否成功。

示例

请求示例

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

返回示例

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

2.3. 删除配置

接口描述

通过该接口，可以删除指定配置。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/cs/config

请求参数

参数名	类型	必填	参数描述
`dataId`	`string`	是	配置ID。
`groupName`	`string`	是	配置分组。
`namespaceId`	`string`	否	命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`boolean`	删除配置是否成功。

示例

请求示例

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

返回示例

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

2.4. 批量删除配置

接口描述

通过该接口，可以批量删除指定配置。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/cs/config/batchDelete

请求参数

参数名	类型	必填	参数描述
`ids`	`string`	是	配置的存储ID列表，并非`dataId`列表，多个ID之间用英文逗号分隔。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`boolean`	删除配置是否成功。

示例

请求示例

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

返回示例

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

2.5. 查询配置列表

接口描述

通过该接口，可以查询指定命名空间下的配置列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/config/list

请求参数

参数名	类型	必填	参数描述
`pageNo`	`integer`	是	当前页码，起始值为1。
`pageSize`	`integer`	是	每页显示的配置数量。
`dataId`	`string`	是	配置ID，当`search`为`blur`时，可使用``进行模糊搜索，例如`test`，当值为“或缺失时，查询全部符合`groupName`条件的配置。
`groupName`	`string`	是	配置分组，当`search`为`blur`时，可使用``进行模糊搜索，例如`test`，当值为“或缺失时，查询全部符合`dataId`条件的配置。
`search`	`string`	否	查询模式，支持`blur`和`accurate`，分别对应模糊搜索和精确搜索，默认值`accurate`
`namespaceId`	`string`	否	命名空间ID，默认值为`public`。
`appName`	`string`	否	配置所属应用名称，默认为空，传入时过滤归属于此应用的配置，值为空时查询所有应用的配置。
`configTags`	`string`	否	配置标签，多个标签之间用英文逗号分隔，默认为空，传入时过滤拥有此tag的配置，值为空时查询所有tag的配置。
`type`	`string`	否	配置的类型，默认值为空，传入时过滤此类型的配置，值为空时查询所有类型的配置。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	符合规则的配置总数。
`pagesAvailable`	`integer`	可用页码总数。
`pageNumber`	`integer`	当前页码。
`pageItems`	`List`	符合规则的配置列表。
`pageItems`[i].`id`	`string`	配置在存储系统中的ID，一般为Long类型的字符串。
`pageItems`[i].`dataId`	`string`	配置ID。
`pageItems`[i].`groupName`	`string`	配置分组。
`pageItems`[i].`namespaceId`	`string`	命名空间ID。
`pageItems`[i].`md5`	`string`	配置内容的MD5值。
`pageItems`[i].`appName`	`string`	配置所属的应用名称。
`pageItems`[i].`type`	`string`	配置类型。
`pageItems`[i].`createTime`	`integer`	配置创建时间。
`pageItems`[i].`modifyTime`	`integer`	配置修改时间。

示例

请求示例

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'

返回示例

{
  "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. 通过配置内容查询配置

接口描述

通过该接口，可以通过配置内容查询对应配置的列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/config/searchDetail

请求参数

参数名	类型	必填	参数描述
`pageNo`	`integer`	是	当前页码，起始值为1。
`pageSize`	`integer`	是	每页显示的配置数量。
`search`	`string`	否	查询模式，支持`blur`和`accurate`，分别对应模糊搜索和精确搜索，默认值`accurate`
`namespaceId`	`string`	否	命名空间ID，默认值为`public`。
`dataId`	`string`	否	配置ID，当`search`为`blur`时，可使用``进行模糊搜索，例如`test`，当值为“或缺失时，查询全部符合`groupName`条件的配置。
`groupName`	`string`	否	配置分组，当`search`为`blur`时，可使用``进行模糊搜索，例如`test`，当值为“或缺失时，查询全部符合`dataId`条件的配置。
`appName`	`string`	否	配置所属应用名称，默认为空，传入时过滤归属于此应用的配置，值为空时查询所有应用的配置。
`configTags`	`string`	否	配置标签，多个标签之间用英文逗号分隔，默认为空，传入时过滤拥有此tag的配置，值为空时查询所有tag的配置。
`type`	`string`	否	配置的类型，默认值为空，传入时过滤此类型的配置，值为空时查询所有类型的配置。
`configDetail`	`string`	是	配置内容检索条件，用于按配置内容过滤，支持模糊匹配（如 `11`）。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	符合规则的配置总数。
`pagesAvailable`	`integer`	可用页码总数。
`pageNumber`	`integer`	当前页码。
`pageItems`	`List`	符合规则的配置列表。
`pageItems`[i].`id`	`string`	配置在存储系统中的ID，一般为Long类型的字符串。
`pageItems`[i].`dataId`	`string`	配置ID。
`pageItems`[i].`groupName`	`string`	配置分组。
`pageItems`[i].`namespaceId`	`string`	命名空间ID。
`pageItems`[i].`md5`	`string`	配置内容的MD5值。
`pageItems`[i].`appName`	`string`	配置所属的应用名称。
`pageItems`[i].`type`	`string`	配置类型。
`pageItems`[i].`createTime`	`integer`	配置创建时间。
`pageItems`[i].`modifyTime`	`integer`	配置修改时间。

示例

请求示例

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*'

返回示例

{
  "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. 查询配置的监听者列表

接口描述

通过该接口，可以查询指定配置的监听者列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/config/listener

请求参数

参数名	类型	必填	参数描述
`dataId`	`string`	是	配置ID。
`groupName`	`string`	是	配置分组。
`namespaceId`	`string`	否	命名空间ID，默认值为`public`。
`aggregation`	`boolean`	否	是否聚合查询。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`queryType`	`string`	订阅者查询类型，该接口为`config`。
`listenersStatus`	`map<string, string>`	订阅者列表，key为订阅者IP，value为订阅者订阅当前配置的MD5值。

示例

请求示例

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

返回示例

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

2.8. 查询某个订阅者IP订阅了哪些配置

接口描述

通过该接口，可以查询某个订阅者IP订阅了哪些配置。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

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

请求参数

参数名	类型	必填	参数描述
`ip`	`string`	是	订阅者IP。
`all`	`boolean`	否	是否查询全部订阅数据。
`namespaceId`	`string`	否	命名空间ID，默认值为`public`。
`aggregation`	`boolean`	否	是否聚合查询。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`queryType`	`string`	订阅者查询类型，该接口为`ip`。
`listenersStatus`	`map<string, string>`	订阅者列表，key为订阅的配置信息，格式为`dataId`+`groupName`+`namespaceId`，value为订阅者订阅当前配置的MD5值。

示例

请求示例

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

返回示例

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

2.9. 导出配置

接口描述

通过该接口，可以将所选或所查询的配置，导出的配置为zip文件，进行备份或导入到其他Nacos集群。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/config/export2

请求参数

参数名	类型	必填	参数描述
`dataId`	`string`	否	需要导出的配置ID的pattern，例如`test*`。
`groupName`	`string`	否	需要导出的配置分组的pattern，例如`test*`。
`ids`	`string`	否	需要导出的配置的存储ID，多个ID用英文逗号分隔。
`namespaceId`	`string`	否	命名空间ID，默认值为`public`。
`appName`	`string`	否	需要导出的配置所属的应用名称。

使用时建议分开使用 ids 和 dataId + groupName 的组合，只选择一种方式，另一类传入空字符串，否则可能导致导出文件为空内容。

返回数据

导出成功是为byte数组的file attachment模式，导出失败时返回体遵循Nacos open API 统一返回体格式。

示例

请求示例

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

返回示例

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

2.10. 导入配置

接口描述

通过该接口，可以将从Nacos导出的zip文件导入到Nacos的指定命名空间中

请求方式

POST

请求体类型：multipart/form-data。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/cs/config/import

请求参数

参数名	类型	必填	参数描述
`file`	`MultipartFile`	否	导入的zip文件。
`namespaceId`	`string`	否	导入的配置所属的命名空间ID，默认值为`public`。
`policy`	`string`	否	导入策略，当导入的配置`dataId`和`groupName`相同，存在冲突时，所进行的导入策略。可选值有`ABORT(终止导入)`,`SKIP(跳过冲突配置)`,`OVERWRITE(覆盖冲突配置)`。默认值为`ABORT`。
`src_user`	`string`	否	导入操作来源用户标识。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`succCount`	`integer`	导入成功的配置数量。
`skipCount`	`integer`	导入跳过的配置数量。

示例

请求示例

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

返回示例

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

2.11. 克隆配置

接口描述

通过该接口，可以将所选或所查询的配置克隆到其他命名空间。

请求方式

POST

请求体类型：application/json，为配置列表数组。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/cs/config/clone

请求参数

参数名	类型	必填	参数描述
`srcUser`	`string`	否	克隆操作来源用户标识。
`targetNamespaceId`	`string`	是	目标命名空间ID。
`policy`	`string`	否	克隆策略，当导入的配置`dataId`和`groupName`相同，存在冲突时，所进行的克隆策略。可选值有`ABORT(终止克隆)`,`SKIP(跳过冲突配置)`,`OVERWRITE(覆盖冲突配置)`。默认值为`ABORT`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`succCount`	`integer`	成功克隆的配置数量。
`skipCount`	`integer`	克隆跳过的配置数量。

示例

请求示例

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\"}]"

返回示例

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

2.12. 停止配置BETA发布

接口描述

通过该接口，可以将配置从BETA发布状态停止，即回滚配置的Beta发布状态。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/cs/config/beta

请求参数

参数名	类型	必填	参数描述
`dataId`	`string`	是	配置的`dataId`。
`groupName`	`string`	是	配置的`groupName`。
`namespaceId`	`string`	否	配置所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述

示例

请求示例

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

返回示例

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

2.13. 查询配置Beta发布状态

接口描述

通过该接口，可以查询配置的BETA发布状态。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/config/beta

请求参数

参数名	类型	必填	参数描述
`dataId`	`string`	是	配置的`dataId`。
`groupName`	`string`	是	配置的`groupName`。
`namespaceId`	`string`	否	配置所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`id`	`string`	beta配置的存储ID。
`dataId`	`string`	配置的dataId。
`groupName`	`string`	配置的groupName。
`namespaceId`	`string`	配置所属的命名空间。
`desc`	`string`	配置描述。
`md5`	`string`	配置内容的MD5值。
`configTags`	`string`	配置的标签。
`encryptedDataKey`	`string`	加密配置内容的密钥，使用配置加密插件时存在。
`appName`	`string`	配置所属的应用名称。
`type`	`string`	配置类型。
`createTime`	`integer`	配置创建时间。
`modifyTime`	`integer`	配置修改时间。
`createUser`	`string`	配置创建人。
`createIp`	`string`	配置创建IP。
`grayName`	`string`	灰度发布规则名称, 固定为`beta`。
`grayRule`	`string`	灰度发布规则，格式为JSON，其中的`expr`为beta的ip列表。

示例

请求示例

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

返回示例

{
  "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. 查询配置发布历史

接口描述

通过该接口，可以查询配置的发布历史。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/history/list

请求参数

参数名	类型	必填	参数描述
`pageNo`	`integer`	是	当前页码，起始为`1`
`pageSize`	`integer`	是	每页显示的记录数。
`dataId`	`string`	是	配置的`dataId`。
`groupName`	`string`	是	配置的`groupName`。
`namespaceId`	`string`	否	配置所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	历史记录的总数。
`pageNumber`	`integer`	当前页码，起始为`1`。
`pagesAvailable`	`integer`	可用页码。
`pageItems`	`List`	历史记录列表。
`pageItems`[i].`id`	`string`	历史记录的ID。
`pageItems`[i].`dataId`	`string`	配置的dataId。
`pageItems`[i].`groupName`	`string`	配置的groupName。
`pageItems`[i].`namespaceId`	`string`	配置所属的命名空间。
`pageItems`[i].`appName`	`string`	配置所属的appName。
`pageItems`[i].`opType`	`string`	操作类型，`I`为插入、`U`为更新、`D`为删除。
`pageItems`[i].`publishType`	`string`	发布类型，`formal`为普通发布，`gray`为beta发布。
`pageItems`[i].`srcIp`	`string`	发布的来源IP。
`pageItems`[i].`srcUser`	`string`	发布的用户，仅在开启鉴权并登录用户后才发布配置才存在。
`pageItems`[i].`createTime`	`integer`	配置创建时间。
`pageItems`[i].`modifyTime`	`integer`	配置修改时间。

示例

请求示例

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

返回示例

{
  "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. 查询配置的某次历史变更记录

接口描述

通过该接口，可以查询配置的某次历史变更记录。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/history

请求参数

参数名	类型	必填	参数描述
`nid`	`integer`	是	历史记录的ID。
`dataId`	`string`	是	配置的dataId。
`groupName`	`string`	是	配置的groupName。
`namespaceId`	`string`	否	配置所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`id`	`string`	历史记录的ID。
`dataId`	`string`	配置的dataId。
`groupName`	`string`	配置的groupName。
`namespaceId`	`string`	配置所属的命名空间。
`content`	`string`
`appName`	`string`	配置所属的appName。
`opType`	`string`	操作类型，`I`为插入、`U`为更新、`D`为删除。
`publishType`	`string`	发布类型，`formal`为普通发布，`gray`为beta发布。
`srcIp`	`string`	发布的来源IP。
`srcUser`	`string`	发布的用户，仅在开启鉴权并登录用户后才发布配置才存在。
`createTime`	`integer`	配置创建时间。
`modifyTime`	`integer`	配置修改时间。
`grayName`	`string`	灰度发布规则名称, 固定为`beta`。
`extInfo`	`JsonString`	扩展信息，目前包括`src_user`、`type`、`c_desc`，若`publishType`为`gray`, 其中还包括`grayRule`。

示例

请求示例

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

返回示例

{
  "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. 查询配置最新状态的前一次变更历史

接口描述

通过该接口，可以查询配置最新状态的前一次变更历史。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/history/previous

请求参数

参数名	类型	必填	参数描述
`id`	`integer`	是	配置的存储ID。
`dataId`	`string`	是	配置的dataId。
`groupName`	`string`	是	配置的groupName。
`namespaceId`	`string`	否	配置所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`id`	`string`	历史记录的ID。
`dataId`	`string`	配置的dataId。
`groupName`	`string`	配置的groupName。
`namespaceId`	`string`	配置所属的命名空间。
`content`	`string`
`appName`	`string`	配置所属的appName。
`opType`	`string`	操作类型，`I`为插入、`U`为更新、`D`为删除。
`publishType`	`string`	发布类型，`formal`为普通发布，`gray`为beta发布。
`srcIp`	`string`	发布的来源IP。
`srcUser`	`string`	发布的用户，仅在开启鉴权并登录用户后才发布配置才存在。
`createTime`	`integer`	配置创建时间。
`modifyTime`	`integer`	配置修改时间。
`grayName`	`string`	灰度发布规则名称, 固定为`beta`。
`extInfo`	`JsonString`	扩展信息，目前包括`src_user`、`type`、`c_desc`，若`publishType`为`gray`, 其中还包括`grayRule`。

示例

请求示例

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

返回示例

{
  "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. 查询命名空间下的配置列表

接口描述

通过该接口，可以查询命名空间下的配置列表，仅查询dataId和groupName，用于配置历史UI的下拉选择。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/cs/history/configs

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	是	配置所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`dataId`	`string`	配置的dataId。
`groupName`	`string`	配置的groupName。

其他字段均无用。

示例

请求示例

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

返回示例

{
  "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. 服务管理

3.1. 创建服务

接口描述

通过该接口，可以创建一个空服务。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ns/service

请求参数

参数名	类型	必填	参数描述
`serviceName`	`string`	是	服务名。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。
`protectThreshold`	`number`	否	服务的防护阈值，默认值为`0.0`。
`selector`	`string`	否	服务的路由选择器，默认值为`{"type":"none"}`，无选择器，另外还支持通过label 进行路由。
`metadata`	`string`	否	服务的元数据，默认值为`{}`。
`ephemeral`	`boolean`	否	服务是否临时，默认值为`false`即持久化服务。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	创建成功时，固定为`ok`。

示例

请求示例

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

返回示例

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

3.2. 删除服务

接口描述

通过该接口，可以删除一个服务。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ns/service

请求参数

参数名	类型	必填	参数描述
`serviceName`	`string`	是	服务名。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	删除成功时，固定为`ok`。

示例

请求示例

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

返回示例

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

3.3. 更新服务元数据

接口描述

通过该接口，可以更新一个服务的元数据。仅能更新服务的元数据，如metadata、selector 等。服务的serviceName、groupName、namespaceId等不能更新。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ns/service

请求参数

参数名	类型	必填	参数描述
`serviceName`	`string`	是	服务名。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。
`protectThreshold`	`number`	否	服务的防护阈值，默认值为`0.0`。
`ephemeral`	`boolean`	否	是否临时实例，如 `true`/`false`。
`selector`	`string`	否	服务的路由选择器，默认值为`{"type":"none"}`，无选择器，另外还支持通过label 进行路由。
`metadata`	`string`	否	服务的元数据，默认值为`{}`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	更新成功时，固定为`ok`。

示例

请求示例

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

返回示例

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

3.4. 获取支持的服务路由选择器类型列表

接口描述

通过该接口，可以获取支持的服务路由选择器类型列表，用于控制台UI在创建和更新服务时，选择对应的路由选择器类型的下拉选择框。

请求方式

GET

鉴权状态

任意有效鉴权身份信息。

请求URL

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

请求参数

无

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`label`	`string`	通过label表达式进行路由选择过滤。
`none`	`string`	无选择器。

示例

请求示例

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

返回示例

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

3.5. 查询服务列表

接口描述

通过该接口，可以查询指定命名空间下的服务列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ns/service/list

请求参数

参数名	类型	必填	参数描述
`pageNo`	`string`	是	页码，起始为`1`。
`pageSize`	`string`	是	每页显示条数。
`serviceNameParam`	`string`	否	服务名的pattern，为空时查询所有服务。
`groupNameParam`	`string`	否	服务所属的groupName的pattern，为空时查询所有服务。
`namespaceId`	`string`	否	服务所属的命名空间ID。
`ignoreEmptyService`	`string`	否	是否仅返回有实例的服务，默认为`false`，即查询空服务。
`withInstances`	`string`	否	是否返回服务的实例详情，默认为`false`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	符合条件的服务的总数。
`pageNumber`	`integer`	当前页码，起始为`1`。
`pagesAvailable`	`integer`	可用页码。
`pageItems`	`List`	服务列表。
`pageItems`[i].`name`	`string`	服务名。
`pageItems`[i].`groupName`	`string`	服务的分组名。
`pageItems`[i].`clusterCount`	`string`	服务下的集群数量。
`pageItems`[i].`ipCount`	`string`	服务下的实例数量。
`pageItems`[i].`healthyInstanceCount`	`string`	服务下的健康实例数量。
`pageItems`[i].`triggerFlag`	`string`	是否触发了服务的保护。

示例

请求示例

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

返回示例

{
  "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. 查询服务的订阅者列表

接口描述

通过该接口，可以查询指定服务下的订阅者列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ns/service/subscribers

请求参数

参数名	类型	必填	参数描述
`pageNo`	`string`	是	页码，起始为`1`。
`pageSize`	`string`	是	每页显示条数。
`serviceName`	`string`	是	服务名。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。
`aggregation`	`string`	否	是否聚合查询。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	符合条件的服务的总数。
`pageNumber`	`integer`	当前页码，起始为`1`。
`pagesAvailable`	`integer`	可用页码。
`pageItems`	`List`	服务列表。
`pageItems`[i].`ip`	`string`	订阅者IP。
`pageItems`[i].`port`	`integer`	订阅者端口。
`pageItems`[i].`address`	`string`	订阅者地址, 一般为`ip:port`。
`pageItems`[i].`agent`	`string`	订阅者客户端版本。
`pageItems`[i].`appName`	`string`	订阅者所属应用。
`pageItems`[i].`namespaceId`	`string`	订阅者所属命名空间。
`pageItems`[i].`groupName`	`string`	订阅的分组名。
`pageItems`[i].`serviceName`	`string`	订阅的服务名。

示例

请求示例

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

返回示例

{
  "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. 查询服务详情

接口描述

通过该接口，可以查询指定服务详情。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ns/service

请求参数

参数名	类型	必填	参数描述
`serviceName`	`string`	是	服务名。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`namespaceId`	`string`	服务所属的namespaceId。
`groupName`	`string`	服务所属的groupName。
`serviceName`	`string`	服务名。
`ephemeral`	`boolean`	服务的持久化属性，`true`为临时服务，`false`为持久化服务。
`protectThreshold`	`number`	服务防护阈值。
`selector`	`jsonObject`	服务选择器。
`metadata`	`jsonObject`	服务元数据。
`clusterMap`	`jsonObject`	服务集群列表, key为cluster的名称，value为集群详细信息。
`clusterMap`.$ClusterName.`clusterName`	`string`	集群名。
`clusterMap`.$ClusterName.`healthChecker`	`jsonObject`	健康检查器。
`clusterMap`.$ClusterName.`healthyCheckPort`	`integer`	健康检查端口。
`clusterMap`.$ClusterName.`useInstancePortForCheck`	`boolean`	是否使用所注册的实例的`IP:Port`进行健康检查。
`clusterMap`.$ClusterName.`metadata`	`jsonObject`	集群元数据。

示例

请求示例

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

返回示例

{
  "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. 更新服务集群元数据

接口描述

通过该接口，可以更新指定服务集群的元数据。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ns/service/cluster

请求参数

参数名	类型	必填	参数描述
`clusterName`	`string`	是	集群名。
`serviceName`	`string`	是	服务名。
`checkPort`	`string`	是	健康检查端口。
`useInstancePort4Check`	`string`	是	是否使用所注册的实例的`IP:Port`进行健康检查。
`healthChecker`	`string`	是	健康检查器。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。
`metadata`	`string`	否	服务元数据。

healthChecker参数为健康检查器的JSON字符串，目前支持三种健康检查器：

None: 无健康检查，{"type":"NONE"}

TCP: TCP端口检查，{"type":"TCP"}

HTTP: HTTP端口检查，{"type":"HTTP","path":"/liveness","headers":"health"}, 其中path为HTTP的uri，headers 为HTTP请求头。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	更新成功时，固定为`ok`。

示例

请求示例

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\"}"

返回示例

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

3.9. 查询服务的实例列表

接口描述

通过该接口，可以查询指定服务的实例列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ns/instance/list

请求参数

参数名	类型	必填	参数描述
`pageNo`	`integer`	是	页码，起始为1。
`pageSize`	`integer`	是	每页记录数。
`serviceName`	`string`	是	服务名。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。
`clusterName`	`string`	否	集群名，不传则查询所有集群的实例。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	符合条件的实例的总数。
`pageNumber`	`integer`	当前页码，起始为`1`。
`pagesAvailable`	`integer`	可用页码。
`pageItems`	`List`	实例列表。
`pageItems`[i].`instanceId`	`string`	实例ID。
`pageItems`[i].`ip`	`string`	实例IP。
`pageItems`[i].`port`	`integer`	实例端口。
`pageItems`[i].`weight`	`number`	实例权重。
`pageItems`[i].`healthy`	`boolean`	实例是否健康。
`pageItems`[i].`enabled`	`boolean`	实例是否已上线。
`pageItems`[i].`ephemeral`	`boolean`	实例是否临时。
`pageItems`[i].`clusterName`	`string`	实例所属集群。
`pageItems`[i].`serviceName`	`string`	实例所属服务，格式为`groupName`@@`serviceName`。
`pageItems`[i].`metadata`	`map<string, string>`	实例元数据。

示例

请求示例

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

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "pageItems": [
      {
        "clusterName": "DEFAULT",
        "enabled": true,
        "ephemeral": false,
        "healthy": false,
        "instanceHeartBeatInterval": 5000,
        "instanceHeartBeatTimeOut": 15000,
        "instanceId": "1.1.1.1#3306#DEFAULT#DEFAULT_GROUP@@test",
        "instanceIdGenerator": "simple",
        "ip": "1.1.1.1",
        "ipDeleteTimeout": 30000,
        "metadata": {},
        "port": 3306,
        "serviceName": "DEFAULT_GROUP@@test",
        "weight": 1.0
      }
    ],
    "pageNumber": 1,
    "pagesAvailable": 1,
    "totalCount": 1
  }
}

3.10. 更新实例元数据

接口描述

通过该接口，可以更新指定服务的实例元数据，包括权重和上下线状态；无法更新实例的服务名、分组名、命名空间、IP及端口。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ns/instance

请求参数

参数名	类型	必填	参数描述
`serviceName`	`string`	是	服务名。
`ip`	`string`	是	实例IP。
`port`	`integer`	是	实例端口。
`groupName`	`string`	否	服务所属的groupName，默认值为`DEFAULT_GROUP`。
`namespaceId`	`string`	否	服务所属的命名空间ID，默认值为`public`。
`clusterName`	`string`	否	实例所属集群, 默认值为`DEFAULT`。
`ephemeral`	`boolean`	否	实例是否临时，默认值为`true`。
`weight`	`number`	否	实例权重。
`healthy`	`boolean`	否	实例健康状态。
`enabled`	`boolean`	否	实例是否已上线。
`metadata`	`string`	否	实例元数据。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	更新成功时，固定为`ok`。

示例

请求示例

curl -X PUT "http://127.0.0.1:8080/v3/console/ns/instance" -d 'serviceName=test&clusterName=DEFAULT&groupName=DEFAULT_GROUP&ip=1.1.1.1&port=3306&ephemeral=true&weight=100&enabled=false&metadata=%7B%22%E5%95%A6%E5%95%A6%E5%95%A6%26%E5%95%B5%E5%95%B5%E5%95%B5%22%3A%22xxx%22%7D'

返回示例

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

4. MCP 管理

4.1. 查询MCP服务的详情

接口描述

通过该接口，可以查询托管在Nacos上指定MCP服务的服务的详细信息。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/mcp

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	MCP服务的命名空间ID，默认为`public`
`mcpId`	`string`	二选一必填	MCP服务的ID，一般为UUID。与`mcpName`二者必须填其一（因 OpenAPI 规范限制，无法在文档中表达“二选一必填”，实际调用时需至少传其中一个）。建议传入`mcpId`。
`mcpName`	`string`	二选一必填	MCP服务的名字模版。与`mcpId`二者必须填其一，建议传入`mcpId`。
`version`	`string`	否	MCP服务的版本，未传入是返回最新版本

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`id`	`string`	MCP服务的ID，一般为UUID。
`name`	`string`	MCP服务名。
`namespaceId`	`string`	MCP服务所属的命名空间ID。
`protocol`	`string`	MCP的协议，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`frontProtocol`	`string`	MCP的前端暴露协议，一般是提供给协议转换器（如网关）使用，若无转换器，则与`protocol`相同，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`description`	`string`	MCP服务的描述。
`repository`	`string`	MCP服务的存储仓库。
`versionDetail`	`VersionDetail`	MCP服务所查询的版本信息。
`localServerConfig`	`Map<String, Object>`	MCP服务若类型为stdio，存在此信息，记录本地MCP服务的启动信息。
`remoteServerConfig`	`RemoteServerConfig`	MCP服务若类型为非stdio，存在此信息，记录远端服务的信息。
`enabled`	`boolean`	MCP服务是否启用。
`capabilities`	`List`	MCP服务支持的能力类型，如`TOOL`,`PROMPT`,`RESOURCE`。
`backendEndpoints`	`List`	MCP服务若类型为非stdio，存在此信息，记录访问远端服务的具体地址信息。
`toolSpec`	`Map<String, Object>`	MCP服务支持的能力类型包含`TOOL`时，存在此信息，记录工具的详细配置信息。
`allVersions`	`List<VersionDetail>`	MCP服务的所有版本详情的列表。

其中VersionDetail结构如下：

参数名	参数类型	描述
`version`	`string`	MCP服务的版本号。
`release_date`	`string`	MCP服务的版本发布时间。
`is_latest`	`boolean`	MCP服务的版本是否为最新版本。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/mcp?namespaceId=public&mcpName=test&mcpId=d7a64724-a556-4fe4-82fa-e806d43e00dc'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "",
    "name": "test",
    "protocol": "stdio",
    "frontProtocol": "stdio",
    "description": "ceshi",
    "repository": null,
    "versionDetail": {
      "version": "1.0.0",
      "release_date": "2025-05-22T06:40:37Z",
      "is_latest": true
    },
    "remoteServerConfig": null,
    "localServerConfig": {
      "test": {}
    },
    "enabled": true,
    "capabilities": [],
    "backendEndpoints": null,
    "toolSpec": null,
    "allVersions": [
      {
        "version": "1.0.0",
        "release_date": "2025-05-22T06:40:37Z",
        "is_latest": true
      }
    ],
    "namespaceId": "public"
  }
}

4.2. 更新MCP服务

接口描述

通过该接口，可以更新托管在Nacos上的MCP服务。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/mcp

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	MCP服务的命名空间ID，默认为`public`
`latest`	`boolean`	否	是否按最新版本更新，如 `true`。
`serverSpecification`	`string`	是	MCP服务的描述详情
`toolSpecification`	`string`	否	MCP服务的工具描述详情
`endpointSpecification`	`string`	否	MCP服务的远端服务地址详情，仅在非`stdio`协议时生效
`overrideExisting`	`boolean`	否	MCP服务更新时是否覆盖原endpointSpecification，默认不覆盖，仅在非`stdio`协议时生效

其中serverSpecification、toolSpecification、endpointSpecification参数的详细内容如下：

serverSpecification

参数名	参数类型	描述
`id`	`string`	MCP服务的ID，一般为UUID，必须传入，用于定位待更新的MCP服务。
`name`	`string`	MCP服务名。
`protocol`	`string`	MCP的协议，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`frontProtocol`	`string`	MCP的前端暴露协议，一般是提供给协议转换器（如网关）使用，若无转换器，则与`protocol`相同，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`description`	`string`	MCP服务的描述。
`repository`	`string`	MCP服务的存储仓库。
`versionDetail`	`VersionDetail`	MCP服务的版本信息。
`version`	`string`	MCP服务的简易版本版本信息，主要用于兼容，若已设置`versionDetail`,则该字段无效。
`localServerConfig`	`Map<String, Object>`	MCP服务若类型为stdio，存在此信息，记录本地MCP服务的启动信息。
`remoteServerConfig`	`RemoteServerConfig`	MCP服务若类型为非stdio，存在此信息，记录远端服务的信息。
`enabled`	`boolean`	MCP服务是否启用。
`capabilities`	`List`	MCP服务支持的能力类型，如`TOOL`,`PROMPT`,`RESOURCE`。

其中VersionDetail结构如下：

参数名	参数类型	描述
`version`	`string`	MCP服务的版本号。
`release_date`	`string`	MCP服务的版本发布时间。
`is_latest`	`boolean`	MCP服务的版本是否为最新版本。

toolSpecification

参数名	参数类型	描述
`tools`	`List<McpTool>`	该MCP Server所提供的工具列表，参考标准MCP协议中对于MCP Tool的定义
`toolsMeta`	`Map<String, McpToolMeta>`	该MCP Server所提供的工具的额外元数据信息，可用于扩展标准MCP协议中未定义但又使用中需要的信息。key为`McpTool`的`name`, value为拓展元数据。
`securitySchemes`	`List<SecurityScheme>`	MCP工具的安全方案，参考标准MCP协议。

其中McpTool结构如下：

参数名	参数类型	描述
`name`	`string`	MCP 工具的名称
`description`	`string`	MCP 工具的描述
`inputSchema`	`Map<String, Object>`	MCP工具的入参描述，参考标准MCP协议，主要包含，`类型`,`是否必须`,`描述` 等。

其中McpToolMeta 结构如下：

参数名	参数类型	描述
`invokeContext`	`map<string, string>`	MCP 工具调用时的上下文信息，如后端服务的`Path`等。
`enabled`	`boolean`	MCP工具是否启用。
`templates`	`map<string, string>`	MCP工具的模板信息。用于进行协议转换时进行参数的映射。

其中SecurityScheme 结构如下：

参数名	参数类型	描述
`id`	`string`	安全方案的ID，将被MCP工具使用和引用。。
`type`	`string`	安全方案的类型。可能的值包括：`http`、`apiKey`、`localEnv`或其他自定义扩展。
`scheme`	`string`	安全方案的子方案类型。当 `type` 为 `http` 时使用。可能的值包括：`basic` 或 `bearer`。
`in`	`string`	安全方案的位置。可能的值有：`query`、`header`。
`name`	`string`	安全方案的名称。当 `type` 为 `apiKey` 或 `localEnv` 时使用。例如，`apiKey` 的密钥名称或 `localEnv` 的环境名称。
`defaultCredential`	`string`	当配置参数中未输入身份时的默认凭证。可选。

endpointSpecification

参数名	参数类型	描述
`type`	`string`	MCP endpoint的后端服务类型，可选值`REF`和`DIRECT`.
`data`	`map<string, string>`	MCP endpoint的后端服务的实际数据，根据`type`的不同，传入的参数不同，如`REF`传入的为`namespaceId`, `groupName` 和 `serviceName`；`DIRECT`传入的为`address` 和 `port`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	MCP服务更新结果。

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/mcp' \
-d 'namespaceId=public' \
-d 'mcpName=test' \
-d 'serverSpecification={"protocol":"stdio","frontProtocol":"stdio","name":"test","id":"d7a64724-a556-4fe4-82fa-e806d43e00dc","description":"ceshi","versionDetail":{"version":"1.0.0"},"enabled":true,"localServerConfig":{"test":{}}}'

返回示例

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

4.3. 创建MCP服务

接口描述

通过该接口，可以创建托管在Nacos上的MCP服务，可以是存量API转换的MCP服务，也可以是MCP市场中的MCP服务。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/mcp

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	MCP服务的命名空间ID，默认为`public`
`serverSpecification`	`string`	是	MCP服务的描述详情
`toolSpecification`	`string`	否	MCP服务的工具描述详情
`endpointSpecification`	`string`	否	MCP服务的远端服务地址详情，仅在非`stdio`协议时生效

其中serverSpecification、toolSpecification、endpointSpecification参数的详细内容如下：

serverSpecification

参数名	参数类型	描述
`id`	`string`	MCP服务的ID，一般为UUID，无需传入，系统自动生成。
`name`	`string`	MCP服务名。
`protocol`	`string`	MCP的协议，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`frontProtocol`	`string`	MCP的前端暴露协议，一般是提供给协议转换器（如网关）使用，若无转换器，则与`protocol`相同，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`description`	`string`	MCP服务的描述。
`repository`	`string`	MCP服务的存储仓库。
`versionDetail`	`VersionDetail`	MCP服务的版本信息。
`version`	`string`	MCP服务的简易版本版本信息，主要用于兼容，若已设置`versionDetail`,则该字段无效。
`localServerConfig`	`Map<String, Object>`	MCP服务若类型为stdio，存在此信息，记录本地MCP服务的启动信息。
`remoteServerConfig`	`RemoteServerConfig`	MCP服务若类型为非stdio，存在此信息，记录远端服务的信息。
`enabled`	`boolean`	MCP服务是否启用。
`capabilities`	`List`	MCP服务支持的能力类型，如`TOOL`,`PROMPT`,`RESOURCE`。

其中VersionDetail结构如下：

参数名	参数类型	描述
`version`	`string`	MCP服务的版本号。
`release_date`	`string`	MCP服务的版本发布时间。
`is_latest`	`boolean`	MCP服务的版本是否为最新版本。

toolSpecification

参数名	参数类型	描述
`tools`	`List<McpTool>`	该MCP Server所提供的工具列表，参考标准MCP协议中对于MCP Tool的定义
`toolsMeta`	`Map<String, McpToolMeta>`	该MCP Server所提供的工具的额外元数据信息，可用于扩展标准MCP协议中未定义但又使用中需要的信息。key为`McpTool`的`name`, value为拓展元数据。
`securitySchemes`	`List<SecurityScheme>`	MCP工具的安全方案，参考标准MCP协议。

其中McpTool结构如下：

参数名	参数类型	描述
`name`	`string`	MCP 工具的名称
`description`	`string`	MCP 工具的描述
`inputSchema`	`Map<String, Object>`	MCP工具的入参描述，参考标准MCP协议，主要包含，`类型`,`是否必须`,`描述` 等。

其中McpToolMeta 结构如下：

参数名	参数类型	描述
`invokeContext`	`map<string, string>`	MCP 工具调用时的上下文信息，如后端服务的`Path`等。
`enabled`	`boolean`	MCP工具是否启用。
`templates`	`map<string, string>`	MCP工具的模板信息。用于进行协议转换时进行参数的映射。

其中SecurityScheme 结构如下：

参数名	参数类型	描述
`id`	`string`	安全方案的ID，将被MCP工具使用和引用。。
`type`	`string`	安全方案的类型。可能的值包括：`http`、`apiKey`、`localEnv`或其他自定义扩展。
`scheme`	`string`	安全方案的子方案类型。当 `type` 为 `http` 时使用。可能的值包括：`basic` 或 `bearer`。
`in`	`string`	安全方案的位置。可能的值有：`query`、`header`。
`name`	`string`	安全方案的名称。当 `type` 为 `apiKey` 或 `localEnv` 时使用。例如，`apiKey` 的密钥名称或 `localEnv` 的环境名称。
`defaultCredential`	`string`	当配置参数中未输入身份时的默认凭证。可选。

endpointSpecification

参数名	参数类型	描述
`type`	`string`	MCP endpoint的后端服务类型，可选值`REF`和`DIRECT`.
`data`	`map<string, string>`	MCP endpoint的后端服务的实际数据，根据`type`的不同，传入的参数不同，如`REF`传入的为`namespaceId`, `groupName` 和 `serviceName`；`DIRECT`传入的为`address` 和 `port`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	新建MCP服务的id。

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/mcp' \
-d 'namespaceId=public' \
-d 'mcpName=test' \
-d 'serverSpecification={"protocol":"stdio","frontProtocol":"stdio","name":"test","id":"","description":"ceshi","versionDetail":{"version":"1.0.0"},"enabled":true,"localServerConfig":{"test":{}}}'

返回示例

{
  "code" : 0,
  "message" : "success",
  "data" : "58e5b430-b16d-4f28-9334-edb64303dc23"
}

4.4. 删除MCP服务

接口描述

通过该接口，可以删除托管在Nacos上的MCP服务。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/mcp

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	MCP服务的命名空间ID，默认为`public`
`mcpId`	`string`	One of two required	MCP service ID (usually UUID). One of `mcpId` and `mcpName` must be provided (OpenAPI cannot express this constraint; at least one is required in practice). Prefer `mcpId`.
`mcpName`	`string`	One of two required	MCP service name template. One of `mcpId` and `mcpName` must be provided; prefer `mcpId`.
`version`	`string`	否	MCP服务的版本，未传入是为最新版本

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	MCP服务删除结果。

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/mcp?namespaceId=public&mcpName=test&mcpId=d7a64724-a556-4fe4-82fa-e806d43e00dc'

返回示例

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

4.5. 查询MCP服务的服务列表

接口描述

通过该接口，可以查询托管在Nacos上的MCP服务的服务列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/mcp/list

请求参数

参数名	参数类型	是否必填	描述
`pageNo`	`integer`	是	当前页，默认为`1`
`pageSize`	`integer`	是	页条目数，默认为`20`，最大为`500`
`namespaceId`	`string`	否	MCP服务的命名空间ID，默认为`public`
`mcpName`	`string`	否	MCP服务的名字模版，为空时查询所有MCP服务，当`search`为`blur`时，可使用`*`进行模糊搜索
`search`	`string`	否	搜索的类型，可选之`blur`和`accurate`，默认为`blur`。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	符合条件的服务的总数。
`pageNumber`	`integer`	当前页码，起始为`1`。
`pagesAvailable`	`integer`	可用页码。
`pageItems`	`List`	服务列表。
`pageItems`[i].`id`	`string`	MCP服务的ID，一般为UUID。
`pageItems`[i].`name`	`string`	MCP服务名。
`pageItems`[i].`protocol`	`string`	MCP的协议，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`pageItems`[i].`frontProtocol`	`string`	MCP的前端暴露协议，一般是提供给协议转换器（如网关）使用，若无转换器，则与`protocol`相同，如`stdio`,`sse`,`streamable`,`http`,`dubbo`等。
`pageItems`[i].`description`	`string`	MCP服务的描述。
`pageItems`[i].`repository`	`string`	MCP服务的存储仓库。
`pageItems`[i].`versionDetail`	`VersionDetail`	MCP服务当前最新的版本信息。
`pageItems`[i].`localServerConfig`	`Map<String, Object>`	MCP服务若类型为stdio，存在此信息，记录本地MCP服务的启动信息。
`pageItems`[i].`remoteServerConfig`	`RemoteServerConfig`	MCP服务若类型为非stdio，存在此信息，记录远端服务的信息。
`pageItems`[i].`latestPublishedVersion`	`string`	MCP服务最新版本的版本号。
`pageItems`[i].`versionDetails`	`List<VersionDetail>`	MCP服务版本详情的列表。
`pageItems`[i].`capabilities`	`List`	MCP服务支持的能力类型，如`TOOL`,`PROMPT`,`RESOURCE`。

其中VersionDetail结构如下：

参数名	参数类型	描述
`version`	`string`	MCP服务的版本号。
`release_date`	`string`	MCP服务的版本发布时间。
`is_latest`	`boolean`	MCP服务的版本是否为最新版本。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/mcp/list?pageNo=1&pageSize=100&namespaceId=public&search=blur'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
      {
        "id": "d7a64724-a556-4fe4-82fa-e806d43e00dc",
        "name": "test",
        "protocol": "stdio",
        "frontProtocol": "stdio",
        "description": "ceshi",
        "repository": null,
        "versionDetail": {
          "version": "1.0.0",
          "release_date": "2025-05-22T06:40:37Z",
          "is_latest": null
        },
        "remoteServerConfig": null,
        "localServerConfig": null,
        "enabled": true,
        "capabilities": null,
        "latestPublishedVersion": "1.0.0",
        "versionDetails": [
          {
            "version": "1.0.0",
            "release_date": "2025-05-22T06:40:37Z",
            "is_latest": null
          }
        ]
      }
    ]
  }
}

4.6. 导入MCP工具

接口描述

通过该接口，可以通过指定MCPURL的方式直接获取MCP工具并导入，避免逐个填写。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/mcp/importToolsFromMcp

请求参数

参数名	参数类型	是否必填	描述
`transportType`	`string`	是	MCP服务的传输协议类型，`mcp-sse`或`mcp-streamable`
`baseUrl`	`string`	是	MCP服务的baseURL
`endpoint`	`string`	是	MCP服务的可访问端点
`authToken`	`string`	否	MCP服务访问的身份Token

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`List<McpSchema.Tool>`	MCP工具元数据信息,符合MCP工具元数据标准定义。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/mcp/importToolsFromMcp?transportType=mcp-sse&baseUrl=%2Fsse&endpoint=http%3A%2F%2Flocalhost'

返回示例

{
  "code" : 0,
  "message" : "success",
  "data" : [ {
    "name" : "getNacosInformation",
    "description" : "Get nacos detail information by nacos cluster name, the information includes nacos hosts and accessToken, accessToken is optional.",
    "inputSchema" : {
      "type" : "object",
      "properties" : {
        "arg0" : {
          "type" : "string",
          "description" : "nacos cluster name"
        }
      },
      "required" : [ "arg0" ],
      "additionalProperties" : false
    }
  } ]
}

4.7. 验证待导入的MCP服务

接口描述

通过该接口，可以验证当前待导入的MCP服务内容是否符合规则，返回的内容中包含有效个数和无效个数，无效的服务在对应字段中有错误信息。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/mcp/import/validate

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	MCP服务的命名空间ID
`importType`	`string`	是	导入的类型，可选值有`file`,`json`和`url`
`data`	`string`	是	导入数据的内容
`cursor`	`string`	否	分页的起始索引
`limit`	`integer`	否	分页的页大小
`search`	`string`	否	导入列表的可选模糊搜索关键字。仅当 importType 为`url`时使用。

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`valid`	`boolean`	导入服务是否合法。
`totalCount`	`integer`	导入服务总数。
`validCount`	`integer`	导入服务有效个数。
`invalidCount`	`integer`	导入服务无效个数。
`duplicateCount`	`integer`	导入服务重复个数。
`servers`	`List<McpServerValidationItem>`	导入服务列表。
`errors`	`List<String>`	导入服务错误列表。

其中McpServerValidationItem描述如下:

参数名	参数类型	描述
`serverName`	`string`	服务名称。
`serverId`	`string`	服务ID。
`status`	`string`	服务状态。
`selected`	`boolean`	服务是否被选中。
`exists`	`boolean`	服务是否已存在。

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/mcp/import/validate' \
-d 'namespaceId=public' \
-d 'importType=url' \
-d 'data=' \
-d 'limit=10'

返回示例

{
  "code" : 0,
  "message" : "success",
  "data" : {
    "valid" : true,
    "totalCount" : 3,
    "validCount" : 3,
    "invalidCount" : 0,
    "duplicateCount" : 0,
    "servers" : [ {
      "serverName" : "server1",
      "serverId" : "id1",
      "status" : "valid",
      "selected" : true,
      "exists" : false
    }, {
      "serverName" : "server2",
      "serverId" : "id2",
      "status" : "valid",
      "selected" : false,
      "exists" : false
    } ],
    "errors" : [ ]
  }
}

4.8. 导入的MCP服务

接口描述

通过该接口，可以通过文件,JSON和指定MCPURL的方式直接导入MCP服务，避免逐个填写。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/mcp/import/execute

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	MCP服务的命名空间ID
`importType`	`string`	是	导入的类型，可选值有`file`,`json`和`url`
`data`	`string`	是	导入数据的内容
`cursor`	`string`	否	分页的起始索引
`limit`	`integer`	否	分页的页大小
`search`	`string`	否	导入列表的可选模糊搜索关键字。仅当 importType 为`url`时使用。
`overrideExisting`	`boolean`	否	导入时若服务已存在时是否覆盖。默认为`false`。
`skipInvalid`	`boolean`	否	导入时是否忽略错误无效的服务。默认为`false`。
`selectedServers`	`string`	否	选择部分服务进行导入,为空时导入所有

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`success`	`boolean`	导入服务是否成功。
`totalCount`	`integer`	导入服务总数。
`successCount`	`integer`	导入服务成功个数。
`failedCount`	`integer`	导入服务失败个数。
`skippedCount`	`integer`	导入服务跳过个数。
`results`	`List<McpServerImportResult>`	导入服务列表。

其中McpServerImportResult描述如下:

参数名	参数类型	描述
`serverName`	`string`	服务名称。
`serverId`	`string`	服务ID。
`status`	`string`	服务导入状态。
`errorMessage`	`boolean`	服务导入失败的错误信息，仅在导入失败时存在。

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/mcp/import/execute' \
-d 'namespaceId=public' \
-d 'importType=url' \
-d 'data=' \
-d 'overrideExisting=false' \
-d 'skipInvalid=false' \
-d 'selectedServers=[]' \
-d 'limit=10'

返回示例

{
  "code" : 0,
  "message" : "success",
  "data" : {
    "success" : true,
    "totalCount" : 5,
    "successCount" : 4,
    "failedCount" : 1,
    "skippedCount" : 0,
    "results" : [ {
      "serverName" : "server1",
      "serverId" : "id1",
      "status" : "success"
    }, {
      "serverName" : "server2",
      "status" : "failed",
      "errorMessage" : "Connection failed"
    } ]
  }
}

5. A2A 注册中心

5.1. 查询AgentCard的列表

接口描述

通过该接口，可以查询托管在Nacos上的AgentCard的列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/a2a/list

请求参数

参数名	参数类型	是否必填	描述
`pageNo`	`integer`	是	当前页，默认为`1`
`pageSize`	`integer`	是	页条目数，默认为`100`
`namespaceId`	`string`	否	AgentCard的命名空间ID，默认为`public`
`agentName`	`string`	否	AgentCard的名称，为空是查询所有AgentCard
`search`	`string`	是	AgentCard名称的匹配模式，可选之`blur`和`accurate`，默认为`blur`

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`totalCount`	`integer`	符合条件的服务的总数。
`pageNumber`	`integer`	当前页码，起始为`1`。
`pagesAvailable`	`integer`	可用页码。
`pageItems`	`List`	服务列表。
`pageItems`[i].`protocolVersion`	`string`	AgentCard的A2A协议版本。
`pageItems`[i].`name`	`string`	AgentCard的名称。
`pageItems`[i].`description`	`string`	AgentCard的描述。
`pageItems`[i].`version`	`string`	AgentCard的版本号。
`pageItems`[i].`iconUrl`	`string`	AgentCard的iconURL。
`pageItems`[i].`capabilities`	`AgentCapability`	AgentCard的能力，匹配A2A标准能力。
`pageItems`[i].`skills`	`List<AgentSkill>`	AgentCard的技能列表,匹配A2A标准技能。
`pageItems`[i].`latestPublishedVersion`	`string`	AgentCard的最新发布版本。
`pageItems`[i].`versionDetails`	`List<AgentVersionDetail>`	AgentCard的所有版本详情。
`pageItems`[i].`registrationType`	`string`	AgentCard的默认注册类型，可选`URL`和`SERVICE`。

其中AgentVersionDetail包含内容如下：

参数名	参数类型	描述
`version`	`string`	AgentCard的版本号。
`createdAt`	`string`	该版本的创建时间。
`updatedAt`	`string`	该版本的最后更新时间。
`latest`	`boolean`	该版本是否标记为最新发布版本。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/a2a/list?pageNo=1&pageSize=100&namespaceId=public&search=blur'

返回示例

{
  "code" : 0,
  "message" : "success",
  "data" : {
    "totalCount" : 1,
    "pageNumber" : 1,
    "pagesAvailable" : 1,
    "pageItems" : [ {
      "protocolVersion" : "0.2.9",
      "name" : "GeoSpatial Route Planner Agent",
      "description" : "Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.",
      "version" : "1.2.0",
      "iconUrl" : "https://georoute-agent.example.com/icon.png",
      "capabilities" : {
        "streaming" : true,
        "pushNotifications" : true,
        "stateTransitionHistory" : false,
        "extensions" : null
      },
      "skills" : [ {
        "id" : "route-optimizer-traffic",
        "name" : "Traffic-Aware Route Optimizer",
        "description" : "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).",
        "tags" : [ "maps", "routing", "navigation", "directions", "traffic" ],
        "examples" : [ "Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.", "{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}" ],
        "inputModes" : [ "application/json", "text/plain" ],
        "outputModes" : [ "application/json", "application/vnd.geo+json", "text/html" ]
      }, {
        "id" : "custom-map-generator",
        "name" : "Personalized Map Generator",
        "description" : "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.",
        "tags" : [ "maps", "customization", "visualization", "cartography" ],
        "examples" : [ "Generate a map of my upcoming road trip with all planned stops highlighted.", "Show me a map visualizing all coffee shops within a 1-mile radius of my current location." ],
        "inputModes" : [ "application/json" ],
        "outputModes" : [ "image/png", "image/jpeg", "application/json", "text/html" ]
      } ],
      "latestPublishedVersion" : "1.2.0",
      "versionDetails" : [ {
        "version" : "1.2.0",
        "createdAt" : "2025-09-12T03:33:51Z",
        "updatedAt" : "2025-09-12T07:21:49Z",
        "latest" : true
      } ],
      "registrationType" : "URL"
    } ]
  }
}

5.2. 查询指定AgentCard的版本列表

接口描述

通过该接口，可以查询指定托管在Nacos上的AgentCard的版本列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/a2a/version/list

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	AgentCard所属的命名空间，默认`public`
`agentName`	`string`	是	AgentCard的名称

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`[i].`version`	`string`	AgentCard的版本号。
`data`[i].`createdAt`	`string`	该版本的创建时间。
`data`[i].`updatedAt`	`string`	该版本的最后更新时间。
`data`[i].`latest`	`boolean`	该版本是否标记为最新发布版本。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/a2a/version/list?namespaceId=public&agentName=GeoSpatial+Route+Planner+Agent'

返回示例

{
  "code" : 0,
  "message" : "success",
  "data" : [ {
    "version" : "1.2.0",
    "createdAt" : "2025-09-12T03:33:51Z",
    "updatedAt" : "2025-09-12T07:21:49Z",
    "latest" : true
  } ]
}

5.3. 查询AgentCard的详情

接口描述

通过该接口，可以查询托管在Nacos上指定AgentCard的详细信息。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/a2a

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	AgentCard所属的命名空间，默认`public`
`agentName`	`string`	是	AgentCard的名称
`version`	`string`	否	AgentCard的版本号，为空时返回最新版本详情
`registrationType`	`string`	否	AgentCard的默认注册类型，可选`URL`和`SERVICE`。未填写时根据此AgentCard的默认`registrationType`进行`url`的生成

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`protocolVersion`	`string`	AgentCard的A2A协议版本。
`name`	`string`	AgentCard的名称。
`description`	`string`	AgentCard的描述。
`version`	`string`	AgentCard的版本号。
`iconUrl`	`string`	AgentCard的iconURL。
`capabilities`	`AgentCapability`	AgentCard的能力，匹配A2A标准能力。
`skills`	`List<AgentSkill>`	AgentCard的技能列表,匹配A2A标准技能。
`url`	`string`	AgentCard的默认访问的URL。
`preferredTransport`	`string`	AgentCard的默认访问URL的传输协议，应该为`JSONRPC`,`GRPC`,`HTTP+JSON`。
`additionalInterfaces`	`List<AgentInterface>`	AgentCard的所有可访问接口列表,匹配A2A标准。
`provider`	`AgentProvider`	AgentCard的提供商信息，匹配A2A标准。
`documentationUrl`	`string`	AgentCard的文档 URL。
`securitySchemes`	`Map<String, SecurityScheme>`	AgentCard的安全配置定义。匹配A2A标准
`security`	`List<Map<String, List<String>>>`	AgentCard的所有安全要求对象列表。
`defaultInputModes`	`List<String>`	AgentCard的所有默认输入模式。
`defaultOutputModes`	`List<String>`	AgentCard的所有默认输出模式。
`supportsAuthenticatedExtendedCard`	`string`	AgentCard是否支持认证的扩展卡。
`registrationType`	`string`	AgentCard的默认注册类型，可选`URL`和`SERVICE`。
`latestVersion`	`string`	AgentCard当前版本时否为最新版本。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/a2a?namespaceId=public&agentName=GeoSpatial+Route+Planner+Agent&version=1.0.0&registrationType=SERVICE'

返回示例

{
  "code" : 0,
  "message" : "success",
  "data" : {
    "protocolVersion" : "0.2.9",
    "name" : "GeoSpatial Route Planner Agent",
    "description" : "Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.",
    "version" : "1.2.0",
    "iconUrl" : "https://georoute-agent.example.com/icon.png",
    "capabilities" : {
      "streaming" : true,
      "pushNotifications" : true,
      "stateTransitionHistory" : false,
      "extensions" : null
    },
    "skills" : [ {
      "id" : "route-optimizer-traffic",
      "name" : "Traffic-Aware Route Optimizer",
      "description" : "Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).",
      "tags" : [ "maps", "routing", "navigation", "directions", "traffic" ],
      "examples" : [ "Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.", "{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}" ],
      "inputModes" : [ "application/json", "text/plain" ],
      "outputModes" : [ "application/json", "application/vnd.geo+json", "text/html" ]
    }, {
      "id" : "custom-map-generator",
      "name" : "Personalized Map Generator",
      "description" : "Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.",
      "tags" : [ "maps", "customization", "visualization", "cartography" ],
      "examples" : [ "Generate a map of my upcoming road trip with all planned stops highlighted.", "Show me a map visualizing all coffee shops within a 1-mile radius of my current location." ],
      "inputModes" : [ "application/json" ],
      "outputModes" : [ "image/png", "image/jpeg", "application/json", "text/html" ]
    } ],
    "url" : "https://georoute-agent.example.com/a2a/v1",
    "preferredTransport" : "JSONRPC",
    "additionalInterfaces" : [ {
      "url" : "https://georoute-agent.example.com/a2a/v1",
      "transport" : "JSONRPC"
    }, {
      "url" : "https://georoute-agent.example.com/a2a/grpc",
      "transport" : "GRPC"
    }, {
      "url" : "https://georoute-agent.example.com/a2a/json",
      "transport" : "HTTP+JSON"
    } ],
    "provider" : {
      "organization" : "Example Geo Services Inc.",
      "url" : "https://www.examplegeoservices.com"
    },
    "documentationUrl" : "https://docs.examplegeoservices.com/georoute-agent/api",
    "securitySchemes" : {
      "google" : {
        "type" : "openIdConnect",
        "openIdConnectUrl" : "https://accounts.google.com/.well-known/openid-configuration"
      }
    },
    "security" : [ {
      "google" : [ "openid", "profile", "email" ]
    } ],
    "defaultInputModes" : [ "application/json", "text/plain" ],
    "defaultOutputModes" : [ "application/json", "image/png" ],
    "supportsAuthenticatedExtendedCard" : true,
    "registrationType" : "URL",
    "latestVersion" : true
  }
}

5.4. 更新AgentCard

接口描述

通过该接口，可以更新托管在Nacos上的AgentCard。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/a2a

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	AgentCard所属的命名空间，默认`public`
`agentCard`	`string`	是	AgentCard的完整对象，详情请参考标准AgentCard
`registrationType`	`string`	否	AgentCard的默认注册类型，可选`URL`和`SERVICE`。未填写时根据此AgentCard的默认`registrationType`进行`url`的生成
`setAsLatest`	`boolean`	否	是否设置此版本为最新发布版本，默认为false

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	AgentCard服务更新结果。

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/a2a' \
-d 'namespaceId=public' \
-d 'agentCard={"protocolVersion":"0.2.9","name":"GeoSpatial Route Planner Agent","description":"Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.","url":"https://georoute-agent.example.com/a2a/v1","preferredTransport":"JSONRPC","additionalInterfaces":[{"url":"https://georoute-agent.example.com/a2a/v1","transport":"JSONRPC"},{"url":"https://georoute-agent.example.com/a2a/grpc","transport":"GRPC"},{"url":"https://georoute-agent.example.com/a2a/json","transport":"HTTP+JSON"}],"provider":{"organization":"Example Geo Services Inc.","url":"https://www.examplegeoservices.com"},"iconUrl":"https://georoute-agent.example.com/icon.png","version":"1.2.0","documentationUrl":"https://docs.examplegeoservices.com/georoute-agent/api","capabilities":{"streaming":true,"pushNotifications":true,"stateTransitionHistory":false},"securitySchemes":{"google":{"type":"openIdConnect","openIdConnectUrl":"https://accounts.google.com/.well-known/openid-configuration"}},"security":[{"google":["openid","profile","email"]}],"defaultInputModes":["application/json","text/plain"],"defaultOutputModes":["application/json","image/png"],"skills":[{"id":"route-optimizer-traffic","name":"Traffic-Aware Route Optimizer","description":"Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).","tags":["maps","routing","navigation","directions","traffic"],"examples":["Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.","{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}"],"inputModes":["application/json","text/plain"],"outputModes":["application/json","application/vnd.geo+json","text/html"]},{"id":"custom-map-generator","name":"Personalized Map Generator","description":"Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.","tags":["maps","customization","visualization","cartography"],"examples":["Generate a map of my upcoming road trip with all planned stops highlighted.","Show me a map visualizing all coffee shops within a 1-mile radius of my current location."],"inputModes":["application/json"],"outputModes":["image/png","image/jpeg","application/json","text/html"]}],"supportsAuthenticatedExtendedCard":true,"signatures":[{"protected":"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0","signature":"QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ"}]}' \
-d 'registrationType=SERVICE' \
-d 'setAsLatest=true'

返回示例

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

5.5. 创建AgentCard

接口描述

通过该接口，可以创建托管在Nacos上的AgentCard。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/a2a

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	AgentCard所属的命名空间，默认`public`
`agentCard`	`string`	是	AgentCard的完整对象，详情请参考标准AgentCard
`registrationType`	`string`	否	AgentCard的默认注册类型，可选`URL`和`SERVICE`。未填写时根据此AgentCard的默认`registrationType`进行`url`的生成, 默认值为`URL`

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	AgentCard发布结果。

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/a2a' \
-d 'namespaceId=public' \
-d 'agentCard={"protocolVersion":"0.2.9","name":"GeoSpatial Route Planner Agent","description":"Provides advanced route planning, traffic analysis, and custom map generation services. This agent can calculate optimal routes, estimate travel times considering real-time traffic, and create personalized maps with points of interest.","url":"https://georoute-agent.example.com/a2a/v1","preferredTransport":"JSONRPC","additionalInterfaces":[{"url":"https://georoute-agent.example.com/a2a/v1","transport":"JSONRPC"},{"url":"https://georoute-agent.example.com/a2a/grpc","transport":"GRPC"},{"url":"https://georoute-agent.example.com/a2a/json","transport":"HTTP+JSON"}],"provider":{"organization":"Example Geo Services Inc.","url":"https://www.examplegeoservices.com"},"iconUrl":"https://georoute-agent.example.com/icon.png","version":"1.2.0","documentationUrl":"https://docs.examplegeoservices.com/georoute-agent/api","capabilities":{"streaming":true,"pushNotifications":true,"stateTransitionHistory":false},"securitySchemes":{"google":{"type":"openIdConnect","openIdConnectUrl":"https://accounts.google.com/.well-known/openid-configuration"}},"security":[{"google":["openid","profile","email"]}],"defaultInputModes":["application/json","text/plain"],"defaultOutputModes":["application/json","image/png"],"skills":[{"id":"route-optimizer-traffic","name":"Traffic-Aware Route Optimizer","description":"Calculates the optimal driving route between two or more locations, taking into account real-time traffic conditions, road closures, and user preferences (e.g., avoid tolls, prefer highways).","tags":["maps","routing","navigation","directions","traffic"],"examples":["Plan a route from '1600 Amphitheatre Parkway, Mountain View, CA' to 'San Francisco International Airport' avoiding tolls.","{\"origin\": {\"lat\": 37.422, \"lng\": -122.084}, \"destination\": {\"lat\": 37.7749, \"lng\": -122.4194}, \"preferences\": [\"avoid_ferries\"]}"],"inputModes":["application/json","text/plain"],"outputModes":["application/json","application/vnd.geo+json","text/html"]},{"id":"custom-map-generator","name":"Personalized Map Generator","description":"Creates custom map images or interactive map views based on user-defined points of interest, routes, and style preferences. Can overlay data layers.","tags":["maps","customization","visualization","cartography"],"examples":["Generate a map of my upcoming road trip with all planned stops highlighted.","Show me a map visualizing all coffee shops within a 1-mile radius of my current location."],"inputModes":["application/json"],"outputModes":["image/png","image/jpeg","application/json","text/html"]}],"supportsAuthenticatedExtendedCard":true,"signatures":[{"protected":"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UiLCJraWQiOiJrZXktMSIsImprdSI6Imh0dHBzOi8vZXhhbXBsZS5jb20vYWdlbnQvandrcy5qc29uIn0","signature":"QFdkNLNszlGj3z3u0YQGt_T9LixY3qtdQpZmsTdDHDe3fXV9y9-B3m2-XgCpzuhiLt8E0tV6HXoZKHv4GtHgKQ"}]}' \
-d 'registrationType=SERVICE'

返回示例

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

5.6. 删除AgentCard

接口描述

通过该接口，可以删除托管在Nacos上的AgentCard。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/a2a

请求参数

参数名	参数类型	是否必填	描述
`namespaceId`	`string`	否	AgentCard所属的命名空间，默认`public`
`agentName`	`string`	是	AgentCard的名称
`version`	`string`	否	AgentCard的版本号，为空时返回最新版本详情

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`string`	AgentCard删除结果。

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/a2a?namespaceId=public&agentName=GeoSpatial+Route+Planner+Agent&version=1.0.0'

返回示例

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

6. Prompt 管理

Prompt 管理 API 提供 Prompt 的发布、查询、标签绑定与版本管理能力。

6.1. 发布Prompt

接口描述

通过该接口，可以发布新版本的Prompt。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/prompt

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	Prompt 的唯一键/标识。
`version`	`string`	是	版本号，如 `1.0.0`。
`template`	`string`	是	Prompt 模板正文内容。
`commitMsg`	`string`	否	本次发布的提交说明。
`description`	`string`	否	Prompt 的描述信息。
`bizTags`	`string`	否	业务标签，用于分类检索，多个标签可逗号分隔。

返回数据

参数名	参数类型	描述
data	`boolean`	是否发布成功。

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/prompt' \
  -d 'namespaceId=public' \
  -d 'promptKey=my-prompt' \
  -d 'version=1.0.0' \
  -d 'template=' \
  -d 'commitMsg=' \
  -d 'description=' \
  -d 'bizTags='

返回示例

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

6.2. 删除Prompt

接口描述

通过该接口，可以删除指定Prompt。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/prompt

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	要删除的 Prompt 的唯一键。

返回数据

参数名	参数类型	描述
data	`boolean`	是否删除成功。

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/prompt?namespaceId=public&promptKey=my-prompt'

返回示例

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

6.3. 查询Prompt详情

接口描述

通过该接口，可按标签/版本/最新优先查询Prompt详情。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/prompt/detail

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	Prompt 的唯一键。
`version`	`string`	否	指定版本号；不传时与 `label`、`md5` 一起决定返回版本（标签或最新等）。
`label`	`string`	否	标签名，如 `stable`、`latest`，返回该标签指向的版本。
`md5`	`string`	否	内容 MD5，用于精确匹配某一版本。

返回数据

参数名	参数类型	描述
data.promptKey	`string`	Prompt 唯一键。
data.version	`string`	版本号。
data.commitMsg	`string`	该版本的提交说明。
data.srcUser	`string`	发布该版本的用户。
data.gmtModified	`integer`	最后修改时间戳。
data.template	`string`	Prompt 模板正文。
data.md5	`string`	内容 MD5。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/prompt/detail?namespaceId=public&promptKey=my-prompt&version=1.0.0&label=&md5='

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "version": "1.0.0",
    "template": "",
    "commitMsg": ""
  }
}

6.4. 绑定标签

接口描述

通过该接口，可将标签绑定到指定Prompt版本。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/prompt/label

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	Prompt 的唯一键。
`label`	`string`	是	标签名，如 `stable`、`latest`。
`version`	`string`	是	要绑定到的版本号。

返回数据

参数名	参数类型	描述
data	`boolean`	是否绑定成功。

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/prompt/label' \
  -d 'namespaceId=public' \
  -d 'promptKey=my-prompt' \
  -d 'label=stable' \
  -d 'version=1.0.0'

返回示例

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

6.5. 解绑标签

接口描述

通过该接口，可解绑Prompt的标签。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/prompt/label

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	Prompt 的唯一键。
`label`	`string`	是	要解绑的标签名。

返回数据

参数名	参数类型	描述
data	`boolean`	是否解绑成功。

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/prompt/label?namespaceId=public&promptKey=my-prompt&label=stable'

返回示例

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

6.6. 查询Prompt列表

接口描述

通过该接口，可以分页查询Prompt列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/prompt/list

请求参数

参数名	类型	必填	参数描述
`pageNo`	`integer`	是	页码，从 1 开始。
`pageSize`	`integer`	是	每页条数。
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	否	按 Prompt 键过滤，支持模糊或精确（由 `search` 决定）。
`search`	`string`	否	搜索模式：`blur` 模糊匹配，`accurate` 精确匹配。
`bizTags`	`string`	否	按业务标签过滤。

返回数据

参数名	参数类型	描述
totalCount	`integer`	总条数。
pageNumber	`integer`	当前页码。
pagesAvailable	`integer`	总页数。
pageItems	`List`	当前页的 Prompt 摘要列表。
pageItems[i].schemaVersion	`integer`	元数据 schema 版本。
pageItems[i].promptKey	`string`	Prompt 唯一键。
pageItems[i].description	`string`	描述。
pageItems[i].bizTags	`array`	业务标签。
pageItems[i].latestVersion	`string`	最新版本号。
pageItems[i].gmtModified	`integer`	最后修改时间戳。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/prompt/list?pageNo=1&pageSize=10&namespaceId=public&promptKey=&search=blur&bizTags='

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
      {
        "promptKey": "my-prompt",
        "description": ""
      }
    ]
  }
}

6.7. 查询Prompt元数据

接口描述

通过该接口，可以查询指定Prompt的元数据信息。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/prompt/metadata

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	Prompt 的唯一键。

返回数据

参数名	参数类型	描述
data.schemaVersion	`integer`	元数据 schema 版本。
data.promptKey	`string`	Prompt 唯一键。
data.description	`string`	描述。
data.bizTags	`array`	业务标签。
data.latestVersion	`string`	最新版本号。
data.gmtModified	`integer`	最后修改时间戳。
data.versions	`array`	版本列表摘要。
data.labels	`object`	标签与版本号的映射。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/prompt/metadata?namespaceId=public&promptKey=my-prompt'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "promptKey": "my-prompt",
    "description": "",
    "bizTags": ""
  }
}

6.8. 更新Prompt元数据

接口描述

通过该接口，可更新Prompt的元数据（如描述、业务标签）。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/prompt/metadata

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	Prompt 的唯一键。
`description`	`string`	否	更新后的描述。
`bizTags`	`string`	否	更新后的业务标签。

返回数据

参数名	参数类型	描述
data	`boolean`	是否更新成功。

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/prompt/metadata' \
  -d 'namespaceId=public' \
  -d 'promptKey=my-prompt' \
  -d 'description=' \
  -d 'bizTags='

返回示例

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

6.9. 查询Prompt版本列表

接口描述

通过该接口，可以分页查询指定Prompt的版本列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/prompt/versions

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`promptKey`	`string`	是	Prompt 的唯一键。
`pageNo`	`integer`	是	页码，从 1 开始。
`pageSize`	`integer`	是	每页条数。

返回数据

参数名	参数类型	描述
totalCount	`integer`	总条数。
pageNumber	`integer`	当前页码。
pagesAvailable	`integer`	总页数。
pageItems	`List`	当前页的版本列表。
pageItems[i].promptKey	`string`	Prompt 唯一键。
pageItems[i].version	`string`	版本号。
pageItems[i].commitMsg	`string`	该版本的提交说明。
pageItems[i].srcUser	`string`	发布该版本的用户。
pageItems[i].gmtModified	`integer`	最后修改时间戳。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/prompt/versions?namespaceId=public&promptKey=my-prompt&pageNo=1&pageSize=10'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
      {
        "version": "1.0.0",
        "commitMsg": ""
      }
    ]
  }
}

7. Skills 管理

Skills 管理 API 提供 Skill 的注册、查询、更新、删除及列表、ZIP 上传能力。

7.1. 查询Skill详情

接口描述

通过该接口，可以查询托管在Nacos上指定Skill的详细信息。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/skills

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`skillName`	`string`	是	Skill 名称/唯一标识。
`version`	`string`	否	版本号；不传则返回最新版本。

返回数据

参数名	参数类型	描述
data.namespaceId	`string`	所属命名空间 ID。
data.name	`string`	Skill 名称。
data.description	`string`	Skill 描述。
data.instruction	`string`	Skill 使用说明/指令。
data.resource	`object`	Skill 关联资源信息。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/skills?namespaceId=public&skillName=my-skill&version=1.0.0'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "name": "my-skill",
    "description": "",
    "instruction": "",
    "resource": {},
    "versionDetail": {
      "version": "1.0.0"
    }
  }
}

7.2. 删除Skill

接口描述

通过该接口，可以删除托管在Nacos上的Skill。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`skillName`	`string`	是	要删除的 Skill 名称。
`version`	`string`	否	版本号；不传则删除该 Skill 下所有版本（或按实现语义）。

返回数据

参数名	参数类型	描述
data	`string`	操作结果，成功时为 `ok`。

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/skills?namespaceId=public&skillName=my-skill&version=1.0.0'

返回示例

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

7.3. 查询Skill列表

接口描述

通过该接口，可以查询托管在Nacos上的Skill列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/skills/list

请求参数

参数名	类型	必填	参数描述
`pageNo`	`integer`	是	页码，从 1 开始。
`pageSize`	`integer`	是	每页条数。
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`skillName`	`string`	否	按 Skill 名称过滤，支持模糊或精确（由 `search` 决定）。
`search`	`string`	否	搜索模式：`blur` 模糊匹配，`accurate` 精确匹配。

返回数据

参数名	参数类型	描述
totalCount	`integer`	总条数。
pageNumber	`integer`	当前页码。
pagesAvailable	`integer`	总页数。
pageItems	`List`	当前页的 Skill 摘要列表。
pageItems[i].namespaceId	`string`	所属命名空间 ID。
pageItems[i].name	`string`	Skill 名称。
pageItems[i].description	`string`	描述。
pageItems[i].updateTime	`integer`	最后更新时间戳。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/skills/list?pageNo=1&pageSize=100&namespaceId=public&skillName=&search=blur'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
      {
        "name": "my-skill",
        "description": "",
        "versionDetail": {
          "version": "1.0.0"
        }
      }
    ]
  }
}

7.4. 上传Skill（ZIP）

接口描述

通过该接口，可通过ZIP文件上传Skill。

请求方式

POST

请求体类型：multipart/form-data。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/upload

请求参数

参数名	类型	必填	参数描述
`file`	`file`	否	包含 Skill 定义的 ZIP 文件。
`namespaceId`	`string`	否	命名空间 ID，不传默认为 `public`。
`overwrite`	`boolean`	否	导入时若 Skill 已存在是否覆盖，默认 `false`。

返回数据

参数名	参数类型	描述
data	`string`	解析并注册后的 Skill 名称。

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/skills/upload' \
  -F "file=@/path/to/skill.zip" \
  -F "namespaceId=public"

返回示例

{
  "code": 0,
  "message": "success",
  "data": "my-skill"
}

7.5. 更新Skill业务标签

接口描述

通过该接口，可更新Skill的业务标签列表，无需变更版本状态。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/biz-tags

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`bizTags`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/skills/biz-tags' -d "namespaceId=namespaceId&skillName=skillName&bizTags=bizTags"

返回示例

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

7.6. 删除Skill草稿版本

接口描述

通过该接口，可删除指定Skill的当前草稿版本。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/draft

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/skills/draft?namespaceId=namespaceId&skillName=skillName'

返回示例

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

7.7. 创建Skill草稿版本

接口描述

通过该接口，可基于某一已有版本或全新 SkillCard 创建草稿版本。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/draft

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	否	-
`basedOnVersion`	`string`	否	-
`targetVersion`	`string`	否	-
`skillCard`	`string`	否	Skill card JSON; required if basedOnVersion is not set

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/skills/draft' -d "namespaceId=namespaceId&skillName=skillName&basedOnVersion=basedOnVersion&targetVersion=targetVersion&skillCard=skillCard"

返回示例

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

7.8. 更新Skill草稿内容

接口描述

通过该接口，可更新当前草稿版本的 SkillCard 内容。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/draft

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`skillCard`	`string`	是	Skill card JSON string containing complete Skill information

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/skills/draft' -d "namespaceId=namespaceId&skillName=skillName&skillCard=skillCard"

返回示例

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

7.9. 更新Skill版本标签

接口描述

通过该接口，可更新Skill的版本路由标签（如 latest 标签），无需变更版本状态。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/labels

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`labels`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/skills/labels' -d "namespaceId=namespaceId&skillName=skillName&labels=labels"

返回示例

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

7.10. 下线Skill

接口描述

通过该接口，可对指定版本或整个Skill执行下线操作，使其不可被调用。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/offline

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`scope`	`string`	否	Use ‘skill’ for skill-level offline; otherwise version-level
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/skills/offline' -d "namespaceId=namespaceId&skillName=skillName&scope=scope&version=version"

返回示例

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

7.11. 上线Skill

接口描述

通过该接口，可对指定版本或整个Skill执行上线操作，使其可被调用。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/online

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`scope`	`string`	否	Use ‘skill’ for skill-level online; otherwise version-level
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/skills/online' -d "namespaceId=namespaceId&skillName=skillName&scope=scope&version=version"

返回示例

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

7.12. 发布Skill版本

接口描述

通过该接口，可将审核通过的Skill版本正式发布。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/publish

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`version`	`string`	是	-
`updateLatestLabel`	`boolean`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/skills/publish' -d "namespaceId=namespaceId&skillName=skillName&version=version&updateLatestLabel=updateLatestLabel"

返回示例

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

7.13. 更新Skill可见范围

接口描述

通过该接口，可将Skill的可见范围设置为 PUBLIC（公开）或 PRIVATE（私有）。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/scope

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`scope`	`string`	是	PUBLIC or PRIVATE

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/skills/scope' -d "namespaceId=namespaceId&skillName=skillName&scope=scope"

返回示例

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

7.14. 提交Skill版本审核

接口描述

通过该接口，可将Skill草稿版本提交至流水线进行审核。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/skills/submit

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/skills/submit' -d "namespaceId=namespaceId&skillName=skillName&version=version"

返回示例

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

7.15. 查询Skill版本详情

接口描述

通过该接口，可按命名空间、Skill名称和版本号查询指定版本的 Skill 详情。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/skills/version

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data.namespaceId	`string`	-
data.data.name	`string`	-
data.data.description	`string`	-
data.data.skillMd	`string`	-
data.data.resource	`object`	-

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/skills/version?namespaceId=namespaceId&skillName=skillName&version=version'

返回示例

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

7.16. 下载Skill版本 ZIP 包

接口描述

通过该接口，可下载指定版本的 Skill ZIP 包。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/skills/version/download

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`skillName`	`string`	是	-
`version`	`string`	否	-

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/skills/version/download?namespaceId=namespaceId&skillName=skillName&version=version'

返回示例

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

8. AgentSpec 管理

AgentSpec 管理 API 提供 AgentSpec 的查询、草稿、发布、上下线及 ZIP 上传等能力。

8.1. 删除 AgentSpec

接口描述

通过该接口，可删除指定命名空间和名称下的 AgentSpec 及其所有版本。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/agentspecs?namespaceId=namespaceId&agentSpecName=agentSpecName'

返回示例

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

8.2. 查询 AgentSpec

接口描述

通过该接口，可按命名空间和名称查询 AgentSpec 的最新已发布版本。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/agentspecs

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data.namespaceId	`string`	-
data.data.name	`string`	-
data.data.description	`string`	-
data.data.updateTime	`integer`	-
data.data.enable	`boolean`	-
data.data.bizTags	`string`	-
data.data.from	`string`	-
data.data.scope	`string`	-
data.data.labels	`object`	-
data.data.editingVersion	`string`	-
data.data.reviewingVersion	`string`	-
data.data.onlineCnt	`integer`	-
data.data.downloadCount	`integer`	-
data.data.versions	`array`	-

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/agentspecs?namespaceId=namespaceId&agentSpecName=agentSpecName&version=version'

返回示例

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

8.3. 更新 AgentSpec 业务标签

接口描述

通过该接口，可更新 AgentSpec 的业务标签列表，无需变更版本状态。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/biz-tags

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`bizTags`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/agentspecs/biz-tags' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&bizTags=bizTags"

返回示例

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

8.4. 删除 AgentSpec 草稿版本

接口描述

通过该接口，可删除指定 AgentSpec 的当前草稿版本。

请求方式

DELETE

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/draft

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8080/v3/console/ai/agentspecs/draft?namespaceId=namespaceId&agentSpecName=agentSpecName'

返回示例

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

8.5. 创建 AgentSpec 草稿版本

接口描述

通过该接口，可基于某一已有版本创建 AgentSpec 草稿版本。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/draft

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`basedOnVersion`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/agentspecs/draft' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&basedOnVersion=basedOnVersion"

返回示例

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

8.6. 更新 AgentSpec 草稿内容

接口描述

通过该接口，可更新当前 AgentSpec 草稿版本的卡片内容。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/draft

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	否	-
`agentSpecCard`	`string`	是	AgentSpec card JSON string containing complete AgentSpec information

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/agentspecs/draft' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&agentSpecCard=agentSpecCard"

返回示例

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

8.7. 更新 AgentSpec 版本标签

接口描述

通过该接口，可更新 AgentSpec 的版本路由标签（如 latest 标签），无需变更版本状态。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/labels

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`labels`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/agentspecs/labels' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&labels=labels"

返回示例

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

8.8. 查询 AgentSpec 列表

接口描述

通过该接口，可按命名空间和名称分页查询 AgentSpec 列表。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/agentspecs/list

请求参数

参数名	类型	必填	参数描述
`pageNo`	`integer`	是	-
`pageSize`	`integer`	是	-
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	否	-
`search`	`string`	否	Search mode: accurate or blur

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/agentspecs/list?pageNo=pageNo&pageSize=pageSize&namespaceId=namespaceId&agentSpecName=agentSpecName&search=search'

返回示例

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

8.9. 下线 AgentSpec

接口描述

通过该接口，可对指定版本或整个 AgentSpec 执行下线操作，使其不可被调用。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/offline

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`scope`	`string`	否	Use ‘agentspec’ for agentspec-level offline; otherwise version-level
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/agentspecs/offline' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&scope=scope&version=version"

返回示例

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

8.10. 上线 AgentSpec

接口描述

通过该接口，可对指定版本或整个 AgentSpec 执行上线操作，使其可被调用。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/online

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`scope`	`string`	否	Use ‘agentspec’ for agentspec-level online; otherwise version-level
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/agentspecs/online' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&scope=scope&version=version"

返回示例

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

8.11. 发布 AgentSpec 版本

接口描述

通过该接口，可将审核通过的 AgentSpec 版本正式发布。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/publish

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`version`	`string`	是	-
`updateLatestLabel`	`boolean`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/agentspecs/publish' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&version=version&updateLatestLabel=updateLatestLabel"

返回示例

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

8.12. 更新 AgentSpec 可见范围

接口描述

通过该接口，可将 AgentSpec 的可见范围设置为 PUBLIC（公开）或 PRIVATE（私有）。

请求方式

PUT

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/scope

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`scope`	`string`	是	PUBLIC or PRIVATE

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X PUT 'http://127.0.0.1:8080/v3/console/ai/agentspecs/scope' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&scope=scope"

返回示例

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

8.13. 提交 AgentSpec 版本审核

接口描述

通过该接口，可将 AgentSpec 草稿版本提交至流水线进行审核。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/submit

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/agentspecs/submit' -d "namespaceId=namespaceId&agentSpecName=agentSpecName&version=version"

返回示例

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

8.14. 上传 AgentSpec

接口描述

通过该接口，可上传 ZIP 格式的 AgentSpec 包，自动解析并创建或更新 AgentSpec。

请求方式

POST

请求体类型：multipart/form-data（如文件上传），请求示例中需使用 -F 或 -H 'Content-Type: multipart/form-data'。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/ai/agentspecs/upload

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`overwrite`	`boolean`	否	-

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`overwrite`	`boolean`	否	-
`file`	`file`	否	ZIP file containing agentspec package

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/ai/agentspecs/upload?namespaceId=namespaceId&overwrite=overwrite' -F "namespaceId=" -F "overwrite=" -F "file="

返回示例

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

8.15. 查询 AgentSpec 版本

接口描述

通过该接口，可按命名空间、名称和版本号查询指定版本的 AgentSpec 详情。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/agentspecs/version

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	-
`agentSpecName`	`string`	是	-
`version`	`string`	否	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data.namespaceId	`string`	-
data.data.name	`string`	-
data.data.description	`string`	-
data.data.bizTags	`string`	-
data.data.content	`string`	-
data.data.resource	`object`	-

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/agentspecs/version?namespaceId=namespaceId&agentSpecName=agentSpecName&version=version'

返回示例

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

9. Pipeline 管理

Pipeline 管理 API 提供执行记录查询能力。

9.1. 查询 Pipeline 执行记录列表

接口描述

通过该接口，可按资源类型、资源名称、命名空间和版本分页查询 Pipeline 执行记录。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/pipelines

请求参数

参数名	类型	必填	参数描述
`resourceType`	`string`	是	-
`resourceName`	`string`	否	-
`namespaceId`	`string`	否	-
`version`	`string`	否	-
`pageNo`	`integer`	是	-
`pageSize`	`integer`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data	`string`	-

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/pipelines?resourceType=resourceType&resourceName=resourceName&namespaceId=namespaceId&version=version&pageNo=pageNo&pageSize=pageSize'

返回示例

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

9.2. 查询 Pipeline 执行记录

接口描述

通过该接口，可按 Pipeline ID 查询 Pipeline 执行记录详情。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/ai/pipelines/{pipelineId}

请求参数

参数名	类型	必填	参数描述
`pipelineId`	`string`	是	-

返回数据

参数名	参数类型	描述
data.code	`integer`	-
data.message	`string`	-
data.data.executionId	`string`	-
data.data.resourceType	`string`	-
data.data.resourceName	`string`	-
data.data.namespaceId	`string`	-
data.data.version	`string`	-
data.data.status	`string`	-
data.data.pipeline	`array`	-
data.data.createTime	`integer`	-
data.data.updateTime	`integer`	-

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/ai/pipelines/{pipelineId}'

返回示例

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

10. Copilot

Copilot 相关 API 提供配置获取/保存、Prompt 调试与优化、Skill 生成与优化等能力（部分接口为 SSE 流式返回）。

10.1. 获取Copilot配置

接口描述

获取当前Copilot配置，仅返回apiKey、model、studioUrl、studioProject。

请求方式

GET

鉴权状态

需要具有对应命名空间读取权限的用户身份。

请求URL

/v3/console/copilot/config

请求参数

无

返回数据

参数名	参数类型	描述
data.enabled	`boolean`	Copilot 功能是否启用。
data.defaultNamespace	`string`	默认使用的命名空间 ID。
data.apiKey	`string`	调用大模型等外部服务的 API Key（脱敏或原文由实现决定）。
data.model	`string`	默认使用的模型标识。
data.studioUrl	`string`	关联的 Studio 服务地址。
data.studioProject	`string`	关联的 Studio 项目标识。

示例

请求示例

curl -X GET 'http://127.0.0.1:8080/v3/console/copilot/config'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "apiKey": "",
    "model": "",
    "studioUrl": "",
    "studioProject": ""
  }
}

10.2. 保存Copilot配置

接口描述

创建或更新Copilot配置，仅接受apiKey、model、studioUrl、studioProject，其他字段使用默认值。

请求方式

POST

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/copilot/config

请求参数

无（请求体可传 apiKey、model、studioUrl、studioProject 等字段，具体以实际接口为准）。

返回数据

参数名	参数类型	描述
data	`boolean`	是否保存成功。

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/copilot/config'

返回示例

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

10.3. 流式调试Prompt

接口描述

通过该接口，可使用用户输入流式调试Prompt并返回模型响应，返回SSE流。

请求方式

POST

请求体类型：application/json。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/copilot/prompt/debug

请求参数

参数名	类型	必填	参数描述
`userInput`	`string`	否	用户输入内容。
`prompt`	`string`	否	待调试的 Prompt。

返回数据

无（SSE 流式返回）

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/copilot/prompt/debug' -H 'Content-Type: application/json' -d '{"userInput":"","prompt":""}'

返回示例

{}

10.4. 流式优化Prompt

接口描述

通过该接口，可流式优化Prompt，返回SSE流。

请求方式

POST

请求体类型：application/json。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/copilot/prompt/optimize

请求参数

参数名	类型	必填	参数描述
`optimizationGoal`	`string`	否	优化目标。
`prompt`	`string`	否	待优化的 Prompt。

返回数据

无（SSE 流式返回）

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/copilot/prompt/optimize' -H 'Content-Type: application/json' -d '{"optimizationGoal":"","prompt":""}'

返回示例

{}

10.5. 流式生成Skill

接口描述

通过该接口，可基于背景信息流式生成Skill，返回SSE流。

请求方式

POST

请求体类型：application/json。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/copilot/skill/generate

请求参数

参数名	类型	必填	参数描述
`backgroundInfo`	`string`	否	背景信息。
`selectedMcpTools`	`array`	否	选中的 MCP 工具。
`conversationHistory`	`object`	否	对话历史。

返回数据

无（SSE 流式返回）

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/copilot/skill/generate' -H 'Content-Type: application/json' -d '{"backgroundInfo":"","selectedMcpTools":"","conversationHistory":""}'

返回示例

{}

10.6. 流式优化Skill

接口描述

通过该接口，可基于目标与对话历史流式优化Skill，返回SSE流。

请求方式

POST

请求体类型：application/json。

鉴权状态

需要具有对应命名空间写入权限的用户身份。

请求URL

/v3/console/copilot/skill/optimize

请求参数

参数名	类型	必填	参数描述
`conversationHistory`	`object`	否	对话历史。
`targetFileName`	`string`	否	目标文件名。
`optimizationGoal`	`string`	否	优化目标。
`skill`	`string`	否	待优化的 Skill 内容。
`selectedMcpTools`	`array`	否	选中的 MCP 工具。

返回数据

无（SSE 流式返回）

示例

请求示例

curl -X POST 'http://127.0.0.1:8080/v3/console/copilot/skill/optimize' -H 'Content-Type: application/json' -d '{"conversationHistory":"","targetFileName":"","optimizationGoal":"","skill":"","selectedMcpTools":""}'

返回示例

{}