Client 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.

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

Request Parameters

Response Data

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

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

Register or renew an instance.

Since

3.0.0

Request Method

POST

Request URL

/nacos/v3/client/ns/instance

Request Headers

Request Parameters

Response Data

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

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&ephemeral=true"

# 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&ephemeral=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

Request Parameters

Response Data

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

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&ephemeral=true"

• 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

Request Parameters

Response Data

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

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

Response Data

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

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

Response Data

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

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

Response Data

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

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

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": {}
}

Agent Management API note: The Agent APIs in sections 3.5–3.10 are the recommended integration path going forward and are planned to gradually replace the existing A2A management APIs. New users and SDKs should prioritize compatibility with these Agent Management APIs instead of adding new dependencies on the legacy A2A APIs. Existing A2A integrations can migrate in line with future release and migration guidance. This describes the evolution of the management APIs and does not mean that the A2A protocol itself is deprecated.

3.5. Discover Agent

Description

Discovers one exact visible Agent version and its currently matching endpoint sets. Supplying X-Nacos-Client-Id renews only an already-existing HTTP Client and cannot replace Publisher heartbeat.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agents

Request Headers

Request Parameters

When both version and label are omitted, the response contains the latest definition metadata and Runtime Endpoints compatible with any currently online version. Explicit label=latest keeps only Runtime Endpoints matching the latest version.

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/agents?namespaceId=public&agentName=my-agent&version=1.0.0&protocol=a2a' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "namespaceId": "public",
    "agentName": "my-agent",
    "version": "1.0.0",
    "contentDigest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "callInterfaces": [
      {
        "protocol": "a2a",
        "protocolVersion": "1.0",
        "descriptorMediaType": "application/json",
        "nativeDescriptor": {
          "name": "my-agent",
          "version": "1.0.0",
          "description": "Example Agent",
          "protocolVersion": "1.0",
          "supportedInterfaces": [
            {
              "url": "https://example.com/my-agent/jsonrpc",
              "protocolBinding": "JSONRPC",
              "protocolVersion": "1.0",
              "transport": "JSONRPC"
            }
          ],
          "capabilities": {
            "streaming": true,
            "extendedAgentCard": true
          }
        },
        "endpointSets": [
          {
            "source": "RUNTIME",
            "sourceRevision": "1",
            "endpoints": [
              {
                "uri": "http://127.0.0.1:8081/a2a",
                "transport": "HTTP+JSON",
                "priority": 0,
                "weight": 1.0,
                "metadata": {},
                "healthy": true,
                "bindings": [
                  {
                    "runtimeVersion": "1.0.0",
                    "versionRange": "[1.0.0]"
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

3.6. Publish Agent Definition

Description

Publishes one exact Agent version from application code, optionally submitting it for review.

Since

3.3.0

Request Method

POST

Request parameters are encoded as an application/x-www-form-urlencoded form.

Request URL

/nacos/v3/client/ai/agents

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -X POST '127.0.0.1:8848/nacos/v3/client/ai/agents' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'namespaceId=public' \
  -d 'agentName=my-agent' \
  -d 'version=1.0.0' \
  --data-urlencode 'callInterfaces=[{"protocol":"a2a","protocolVersion":"1.0","descriptorMediaType":"application/json","nativeDescriptor":{"name":"my-agent","version":"1.0.0","description":"Example Agent","protocolVersion":"1.0","supportedInterfaces":[{"url":"https://example.com/my-agent/jsonrpc","protocolBinding":"JSONRPC","protocolVersion":"1.0","transport":"JSONRPC"}],"capabilities":{"streaming":true,"extendedAgentCard":true}},"endpointSourceOrder":["DECLARED","RUNTIME"],"declaredEndpoints":[{"uri":"https://example.com/my-agent/jsonrpc","transport":"JSONRPC"}]}]' \
  -d 'author=demo' \
  -d 'changeDescription=initial version' \
  -d 'autoSubmit=true'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "namespaceId": "public",
    "agentName": "my-agent",
    "version": "1.0.0",
    "status": "draft",
    "callInterfaces": [
      {
        "protocol": "a2a",
        "protocolVersion": "1.0",
        "descriptorMediaType": "application/json",
        "nativeDescriptor": {
          "name": "my-agent",
          "version": "1.0.0",
          "description": "Example Agent",
          "protocolVersion": "1.0",
          "supportedInterfaces": [
            {
              "url": "https://example.com/my-agent/jsonrpc",
              "protocolBinding": "JSONRPC",
              "protocolVersion": "1.0",
              "transport": "JSONRPC"
            }
          ],
          "capabilities": {
            "streaming": true,
            "extendedAgentCard": true
          }
        },
        "endpointSourceOrder": ["DECLARED", "RUNTIME"],
        "declaredEndpoints": [
          {
            "uri": "https://example.com/my-agent/jsonrpc",
            "transport": "JSONRPC"
          }
        ]
      }
    ],
    "author": "demo",
    "changeDescription": "initial version",
    "contentDigest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "createTime": 1785897600000,
    "updateTime": 1785897600000
  }
}

3.7. Register Agent Endpoints

Description

Replaces one HTTP publisher’s complete runtime endpoint batch for an Agent protocol. Reuse one stable X-Nacos-Client-Id for every batch owned by the same logical client in its bound namespace. The returned ClientLivenessInfo is the effective server policy: schedule one heartbeat task for this client id at heartbeatIntervalMillis, not one task per endpoint or batch.

Since

3.3.0

Request Method

POST

Request parameters are encoded as an application/x-www-form-urlencoded form; endpoints is a JSON array string.

Request URL

/nacos/v3/client/ai/agents/endpoints

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -X POST '127.0.0.1:8848/nacos/v3/client/ai/agents/endpoints' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Request-Module: AI' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'namespaceId=public' \
  -d 'agentName=my-agent' \
  -d 'runtimeVersion=1.0.0' \
  --data-urlencode 'versionRange=[1.0.0]' \
  -d 'protocol=a2a' \
  --data-urlencode 'endpoints=[{"uri":"http://127.0.0.1:8081/a2a","transport":"HTTP+JSON","priority":0,"weight":1.0,"metadata":{}}]'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "heartbeatIntervalMillis": 5000,
    "unhealthyTimeoutMillis": 15000,
    "expireTimeoutMillis": 30000
  }
}

3.8. Deregister Agent Endpoints

Description

Removes one HTTP publisher’s complete runtime endpoint publication for an Agent protocol owned by the supplied X-Nacos-Client-Id. Keep one client-level heartbeat while any publication owned by this client remains, and stop it after the last publication is removed.

This endpoint binds the ordinary namespaceId, agentName, and protocol request parameters through a dedicated form. It does not accept Endpoint natural keys or a JSON request body.

Since

3.3.0

Request Method

DELETE

Request URL

/nacos/v3/client/ai/agents/endpoints

Request Headers

Request Parameters

Response Data

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

Examples

• Request example

curl -X DELETE '127.0.0.1:8848/nacos/v3/client/ai/agents/endpoints?namespaceId=public&agentName=my-agent&protocol=a2a' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Request-Module: AI'

• Response example

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

3.9. Heartbeat Agent Endpoints

Description

Refreshes the HTTP Client and every Agent endpoint publication owned by its X-Nacos-Client-Id. Send one heartbeat task per client id regardless of endpoint, Agent, protocol, or batch count; never schedule heartbeats per endpoint. Use heartbeatIntervalMillis returned by registration or the latest heartbeat as the delay before the next heartbeat, and reschedule when a later response changes it instead of hard-coding the current defaults. unhealthyTimeoutMillis and expireTimeoutMillis are effective server thresholds and cannot be overridden by the request. Search and Discover do not renew Publisher liveness. On HTTP_CLIENT_NOT_FOUND (50404), re-register every complete desired batch before continuing heartbeats.

Since

3.3.0

Request Method

PUT

Request URL

/nacos/v3/client/ai/agents/endpoints/heartbeat

Request Headers

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -X PUT '127.0.0.1:8848/nacos/v3/client/ai/agents/endpoints/heartbeat' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Request-Module: AI'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "heartbeatIntervalMillis": 5000,
    "unhealthyTimeoutMillis": 15000,
    "expireTimeoutMillis": 30000
  }
}

3.10. Search Agent Catalog

Description

Searches visible Agent catalog entries by name, tags, protocols, and pagination. Supplying X-Nacos-Client-Id renews only an already-existing HTTP Client and never its endpoint Publisher liveness.

Since

3.3.0

Request Method

GET

Request URL

/nacos/v3/client/ai/agents/search

Request Headers

Request Parameters

Response Data

The response body follows the Nacos OpenAPI common response format. The following table describes data and its fields.

Examples

• Request example

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/agents/search?namespaceId=public&agentNameContains=agent&tagsAll=assistant&protocolsAny=a2a&pageNo=1&pageSize=10' \
  -H 'X-Nacos-Client-Id: 550e8400-e29b-41d4-a716-446655440000'

• Response example

{
  "code": 0,
  "message": "success",
  "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
      {
        "agentName": "my-agent",
        "displayName": "My Agent",
        "description": "Example Agent",
        "iconUrl": "https://example.com/icon.png",
        "provider": {
          "name": "example-provider",
          "url": "https://example.com"
        },
        "tags": ["assistant"],
        "latestVersion": "1.0.0",
        "versions": [
          {
            "version": "1.0.0",
            "labels": ["latest"],
            "protocols": ["a2a"]
          }
        ]
      }
    ]
  }
}