Client API

Nacos 3.X is no longer compatible with the OpenAPI of Nacos 1.X or the HTTP OpenAPI of Nacos 2.X. Please migrate to the OpenAPI of Nacos 3.X.

The HTTP OpenAPI in Nacos 3.X is mainly intended for clients written in programming languages that do not support gRPC. It provides configuration retrieval, service registration, and service discovery capabilities for regular applications, microservice applications, and other non-control-plane or non-gateway applications.

These APIs only provide data operations at the single-service or single-configuration level, such as reading or updating an individual service or configuration item. They do not support range-based aggregate operations, such as querying all services or all configurations.

For control-plane or gateway applications that require range-based data operations, use the Admin API.

For how to obtain and configure access credentials when using the default auth plugin, see Configure Access Credentials.

0. Client API Notes

0.1. Scope

Client APIs are intended for application runtime access and custom clients. Callers usually already know the namespaceId, groupName, dataId, serviceName, or instance information they need to access.

Good Fit	Not a Good Fit
Querying a single known configuration.	Publishing, deleting, importing, or exporting configurations.
Registering, deregistering, querying, and discovering known services or instances.	Querying full configuration lists, full service lists, subscriber lists, or other range-based data.
Using HTTP for a small amount of runtime access when no suitable SDK is available.	Building release platforms, operations platforms, gateway control planes, or audit tools.

Business applications should prefer SDKs. For range-based management capabilities, use Admin API or Maintainer SDK.

0.2. Unified Path Format

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

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

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

The examples below also use the default Nacos Web Server port. If the deployment changes $nacos.server.main.port, update the request URL accordingly when calling the API.

0.3. Swagger Documentation

Nacos 3.X client OpenAPI also provides Swagger-style documentation. You can view it at Nacos Swagger HTTP Client API.

1. Configuration Management

1.1. Get Configuration

Description

Get the specified configuration.

Since

3.0.0

Request Method

GET

Request URL

/nacos/v3/client/cs/config

Request Headers

Name	Type	Required	Description
`User-Agent`	`string`	No	User agent. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.
`Client-Version`	`string`	No	Client version. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace. Defaults to `public`, which is equivalent to `''`.
`groupName`	`string`	Yes	Configuration group name.
`dataId`	`string`	Yes	Configuration name.

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Name	Type	Description
`content`	`string`	Configuration content.
`encryptedDataKey`	`string`	Encryption/decryption key of the configuration. This value exists only when a configuration encryption plugin is used.
`contentType`	`string`	Configuration type, such as `TEXT` or `JSON`.
`md5`	`string`	MD5 value of the configuration.
`lastModified`	`integer`	Last modification time of the configuration.
`beta`	`boolean`	Whether the configuration has a beta configuration.

Other fields are reserved and currently unused. You can ignore them.

Examples

Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/cs/config?dataId=test&groupName=test'

Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "resultCode": 200,
    "errorCode": 0,
    "message": null,
    "requestId": null,
    "content": "test",
    "encryptedDataKey": null,
    "contentType": "text",
    "md5": "098f6bcd4621d373cade4e832627b4f6",
    "lastModified": 1743151634823,
    "tag": null,
    "beta": false,
    "success": true
  }
}

2. Service Discovery

2.1. Register/Renew Instance

Description

When an instance registered through the HTTP OpenAPI is an ephemeral instance, it must be renewed periodically. In the HTTP OpenAPI of Nacos 3.X, the renewal API and registration API are merged and distinguished by the heartBeat parameter.

For renewal requests, Nacos does not parse metadata and related fields in the request. In other words, renewal requests ignore the healthy, weight, enabled, and metadata fields. If a renewal request returns error code 21003, the instance has expired and been removed. The client should re-register the instance with complete information and set heartBeat=false, then continue renewal requests after registration succeeds.

Calling the registration request repeatedly can also renew the instance, but it renews by updating the instance and consumes more resources. Therefore, after registration succeeds, use renewal instead of repeated registration updates.

Since

3.0.0

Request Method

POST

Request URL

/nacos/v3/client/ns/instance

Request Headers

Name	Type	Required	Description
`User-Agent`	`string`	No	User agent. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.
`Client-Version`	`string`	No	Client version. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace ID. Defaults to `public`.
`groupName`	`string`	No	Group name. Defaults to `DEFAULT_GROUP`.
`serviceName`	`string`	Yes	Service name.
`ip`	`string`	Yes	IP address.
`port`	`integer`	Yes	Port.
`clusterName`	`string`	No	Cluster name. Defaults to `DEFAULT`.
`healthy`	`boolean`	No	Whether the instance is healthy. Defaults to `true`.
`weight`	`number`	No	Instance weight. Defaults to `1.0`.
`enabled`	`boolean`	No	Whether the instance is enabled. Defaults to `true`.
`metadata`	`string`	No	Instance metadata as a JSON object string.
`heartBeat`	`boolean`	No	Whether this is a renewal request. Defaults to `false`.

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Name	Type	Description
`data`	`string`	Whether registration or renewal succeeded. Returns `ok` on success, or the failure reason on failure.

Examples

Request example

# Register instance
curl -X POST "127.0.0.1:8848/nacos/v3/client/ns/instance" -d "serviceName=test1&ip=127.0.0.1&port=3306"

# Renew instance
curl -X POST "127.0.0.1:8848/nacos/v3/client/ns/instance" -d "serviceName=test1&ip=127.0.0.1&port=3306&heartBeat=true"

Response example

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

2.2. Deregister Instance

Description

Deregister the specified instance.

Since

3.0.0

Request Method

DELETE

Request URL

/nacos/v3/client/ns/instance

Request Headers

Name	Type	Required	Description
`User-Agent`	`string`	No	User agent. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.
`Client-Version`	`string`	No	Client version. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace ID. Defaults to `public`.
`groupName`	`string`	No	Group name. Defaults to `DEFAULT_GROUP`.
`serviceName`	`string`	Yes	Service name.
`ip`	`string`	Yes	IP address.
`port`	`integer`	Yes	Port.
`clusterName`	`string`	No	Cluster name. Defaults to `DEFAULT`.

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Name	Type	Description
`data`	`string`	Whether deregistration succeeded. Returns `ok` on success, or the failure reason on failure.

Examples

Request example

curl -X DELETE "127.0.0.1:8848/nacos/v3/client/ns/instance?serviceName=test1&ip=127.0.0.1&port=3306"

Response example

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

2.3. List Instances of a Service

Description

Query the detailed instance list under the specified service.

Since

3.0.0

Request Method

GET

Request URL

/nacos/v3/client/ns/instance/list

Request Headers

Name	Type	Required	Description
`User-Agent`	`string`	No	User agent. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.
`Client-Version`	`string`	No	Client version. It is empty by default and is usually `Nacos-${program-language}-Client:v${version}`.

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace ID. Defaults to `public`.
`groupName`	`string`	No	Group name. Defaults to `DEFAULT_GROUP`.
`serviceName`	`string`	Yes	Service name.
`clusterName`	`string`	No	Cluster name. If not provided, instances of all clusters will be returned.

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Name	Type	Description
`data`	`array`	Instance list.
`data.[i].ip`	`string`	Instance IP.
`data.[i].port`	`integer`	Instance port.
`data.[i].weight`	`number`	Instance weight.
`data.[i].healthy`	`boolean`	Whether the instance is healthy.
`data.[i].enabled`	`boolean`	Whether the instance is enabled.
`data.[i].ephemeral`	`boolean`	Whether the instance is ephemeral.
`data.[i].clusterName`	`string`	Cluster name of the instance.
`data.[i].serviceName`	`string`	Service name.
`data.[i].metadata`	`map<string, string>`	Instance metadata.
`data.[i].instanceHeartBeatTimeOut`	`integer`	Instance heartbeat timeout.
`data.[i].ipDeleteTimeout`	`integer`	Instance deletion timeout.
`data.[i].instanceHeartBeatInterval`	`integer`	Instance heartbeat interval.

Examples

Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/ns/instance/list?serviceName=test1'

Response example

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "ip": "127.0.0.1",
      "port": 3306,
      "weight": 1.0,
      "healthy": true,
      "enabled": true,
      "ephemeral": true,
      "clusterName": "DEFAULT",
      "serviceName": "DEFAULT_GROUP@@test1",
      "metadata": {},
      "ipDeleteTimeout": 30000,
      "instanceIdGenerator": "simple",
      "instanceHeartBeatInterval": 5000,
      "instanceHeartBeatTimeOut": 15000
    }
  ]
}

3. AI

3.1. Query Prompt

Description

Query Prompt by version, label, or latest (priority: version > label > latest); supports md5 for 304 conditional response.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/prompt

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace ID. Defaults to `public`.
`promptKey`	`string`	Yes	Prompt key
`version`	`string`	No	Version (one of version, label, latest)
`label`	`string`	No	Label (one of version, label, latest)
`md5`	`string`	No	If matches server, response is 304

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes only the fields in data.

Name	Type	Description
`promptKey`	`string`	Prompt key
`version`	`string`	Version
`template`	`string`	Prompt template content
`md5`	`string`	Content md5 for 304
`variables`	`array`	Prompt variable list

Examples

Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/prompt?promptKey=myPrompt'

Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "promptKey": "myPrompt",
    "version": "1.0",
    "template": "You are a helpful assistant.",
    "md5": "..."
  }
}

3.2. Get AgentSpec

Description

This interface allows getting an AgentSpec detail by namespace, name, version, or label.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agentspecs

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace ID, default is `public`
`name`	`string`	Yes	AgentSpec name
`version`	`string`	No	AgentSpec version
`label`	`string`	No	AgentSpec label
`md5`	`string`	No	AgentSpec content MD5 for exact version matching

Response Data

Return body follows Nacos open API common response format; this table describes fields in data.

Name	Type	Description
`namespaceId`	`string`	Namespace of the AgentSpec
`name`	`string`	AgentSpec name
`description`	`string`	AgentSpec description
`bizTags`	`string`	AgentSpec business tags
`content`	`string`	AgentSpec content
`resource`	`object`	AgentSpec resource info

Examples

Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/agentspecs?name=my-agent'

Response example

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

3.3. Search AgentSpecs

Description

This interface allows paginated searching of AgentSpecs by namespace and keyword.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agentspecs/search

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace ID, default is `public`
`keyword`	`string`	No	Search keyword
`pageNo`	`integer`	Yes	Page number, typically starts from `1`
`pageSize`	`integer`	Yes	Number of records per page

Response Data

Return body follows Nacos open API common response format; this table describes fields in data.

Name	Type	Description
`data`	`string`	AgentSpec search result (paginated object, actual fields depend on runtime response)

Examples

Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/agentspecs/search?keyword=agent&pageNo=1&pageSize=10'

Response example

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

3.4. Download Skill

Description

This interface allows downloading a Skill ZIP file by namespace, name, version, or label.

Since

3.2.0

Request Method

GET

Request URL

/nacos/v3/client/ai/skills

Request Parameters

Name	Type	Required	Description
`namespaceId`	`string`	No	Namespace ID, default is `public`
`name`	`string`	Yes	Skill name
`version`	`string`	No	Skill version
`label`	`string`	No	Skill label
`md5`	`string`	No	Skill content MD5 for exact version matching

Examples

Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/skills?name=my-skill'

Response example

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