API Reference

NvwaX Developer API 完整文档。所有公开 API 使用 API Key 认证（Authorization: Bearer nvwx_xxx）。

认证方式#

所有 API 请求需要在 HTTP Header 中携带 API Key：

Authorization: Bearer nvwx_your_api_key_here

API Key 可在用户中心 > Profile > API Keys 页面创建。不同权限的 Key 可以访问不同的 API 端点。

Marketplace - Agent/AiTeam 市场#

GET/api/v1/marketplace/agents

搜索已发布的 Agent 列表

认证方式: API Key (marketplace:read)

请求参数

参数名类型必填说明
qstring否搜索关键词
categorystring否分类过滤
tagsstring否标签过滤（逗号分隔）
pagenumber否页码，默认 1
limitnumber否每页数量，最大 50，默认 20

响应示例

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent-uuid",
        "name": "电商客服 Agent",
        "description": "智能客服机器人...",
        "category": "customer-service",
        "tags": ["ecommerce", "chatbot"],
        "rating": 4.7,
        "download_count": 1523,
        "publish_status": "published"
      }
    ],
    "total": 156
  }
}
GET/api/v1/marketplace/agents/:id

获取单个 Agent 完整详情

认证方式: API Key (marketplace:read)

GET/api/v1/marketplace/categories

获取 Agent 分类列表（含各分类数量）

认证方式: API Key (marketplace:read)

GET/api/v1/marketplace/aiteams

搜索已发布的 AiTeam 列表

认证方式: API Key (marketplace:read)

请求参数

参数名类型必填说明
qstring否搜索关键词
industrystring否行业过滤
pagenumber否页码，默认 1
limitnumber否每页数量，最大 50，默认 20
GET/api/v1/marketplace/aiteams/:id

获取单个 AiTeam 完整详情

认证方式: API Key (marketplace:read)

GET/api/v1/marketplace/industries

获取行业分类列表

认证方式: API Key (marketplace:read)

GET/api/v1/marketplace/plugins/:id

获取行业插件详情（含 Agent 明细）

认证方式: API Key (marketplace:read)

Agents - Agent 管理#

POST/api/v1/agents

创建新的 Agent

认证方式: API Key (agent:create)

请求示例

{
  "name": "我的自定义 Agent",
  "description": "用于处理订单查询的智能体",
  "config": {
    "model": "deepseek-v3",
    "temperature": 0.7,
    "system_prompt": "你是一个订单查询助手..."
  },
  "skills": ["order-query"],
  "category": "customer-service",
  "tags": ["ecommerce", "order"]
}
GET/api/v1/agents

列出当前开发者创建的所有 Agent

认证方式: API Key (agent:read)

请求参数

参数名类型必填说明
statusstring否过滤状态: draft, published, private
pagenumber否页码，默认 1
limitnumber否每页数量，默认 20
GET/api/v1/agents/:id

获取自己的 Agent 详情

认证方式: API Key (agent:read)

PUT/api/v1/agents/:id

更新 Agent 配置

认证方式: API Key (agent:update)

DELETE/api/v1/agents/:id

删除 Agent

认证方式: API Key (agent:delete)

POST/api/v1/agents/:id/publish

发布 Agent 到市场

认证方式: API Key (agent:publish)

POST/api/v1/agents/:id/unpublish

取消发布 Agent

认证方式: API Key (agent:publish)

AiTeams - AiTeam 管理#

POST/api/v1/aiteams

创建新的 AiTeam

认证方式: API Key (aiteam:create)

请求示例

{
  "name": "电商运营团队",
  "description": "负责电商日常运营的 AI 团队",
  "members": [
    { "agent_id": "agent-uuid-1", "role": "客服主管" },
    { "agent_id": "agent-uuid-2", "role": "数据分析师" }
  ],
  "category": "ecommerce",
  "tags": ["operations"]
}
GET/api/v1/aiteams

列出当前开发者创建的所有 AiTeam

认证方式: API Key (aiteam:read)

GET/api/v1/aiteams/:id

获取自己的 AiTeam 详情

认证方式: API Key (aiteam:read)

PUT/api/v1/aiteams/:id

更新 AiTeam 配置

认证方式: API Key (aiteam:update)

DELETE/api/v1/aiteams/:id

删除 AiTeam

认证方式: API Key (aiteam:delete)

POST/api/v1/aiteams/:id/publish

发布 AiTeam 到市场

认证方式: API Key (aiteam:publish)

POST/api/v1/aiteams/:id/unpublish

取消发布 AiTeam

认证方式: API Key (aiteam:publish)

Search - 搜索#

GET/api/v1/search/agents

全网 Agent 搜索（GitHub / HuggingFace / 本地）

认证方式: API Key (search:read)

请求参数

参数名类型必填说明
qstring是搜索关键词
pagenumber否页码，默认 1
limitnumber否每页数量，最大 50，默认 20
GET/api/v1/search/skills

SkillHub 技能搜索

认证方式: API Key (search:read)

请求参数

参数名类型必填说明
qstring是搜索关键词
pagenumber否页码，默认 1
limitnumber否每页数量，最大 50，默认 20
POST/api/v1/search/unified

统一搜索（同时搜索 Agents + Skills）

认证方式: API Key (search:read)

请求示例

{
  "q": "客服机器人",
  "page": 1,
  "limit": 20
}

Export - 导出下载#

POST/api/v1/agents/:id/export

导出 Agent（JSON / YAML / ProClaw 格式）

认证方式: API Key (export:read)

请求示例

{
  "format": "json",
  "includeMetadata": true,
  "includeImplementation": false
}
POST/api/v1/aiteams/:id/export

导出 AiTeam（JSON / YAML / ProClaw 格式）

认证方式: API Key (export:read)

请求示例

{
  "format": "json",
  "includeMetadata": true
}
POST/api/v1/export/batch

批量导出多个 Agent/AiTeam

认证方式: API Key (export:read)

请求示例

{
  "items": [
    { "type": "agent", "id": "agent-uuid-1" },
    { "type": "aiteam", "id": "aiteam-uuid-2" }
  ],
  "format": "json"
}
GET/api/v1/export/history

获取导出历史记录

认证方式: API Key (export:read)

请求参数

参数名类型必填说明
limitnumber否返回条数，默认 20

错误码#

状态码错误码说明
400VALIDATION_ERROR请求参数验证失败
401MISSING_AUTH_HEADER / INVALID_API_KEY缺少认证信息或 API Key 无效
403INSUFFICIENT_PERMISSIONSAPI Key 权限不足
404NOT_FOUND请求的资源不存在
429RATE_LIMIT_EXCEEDED超过速率限制
500INTERNAL_ERROR服务器内部错误

SDK 快速用法

import { createClient } from '@nvwax/sdk';

const client = createClient('nvwx_your_api_key');

// 浏览市场
const agents = await client.marketplace.searchAgents({ q: '客服', limit: 10 });

// 管理 Agent
const myAgent = await client.agents.create({ name: '我的 Agent', description: '...' });
await client.agents.publish(myAgent.data.id);

// 管理 AiTeam
const team = await client.aiteams.create({
  name: '运营团队',
  members: [{ agent_id: agentId, role: '主管' }]
});

// 搜索
const results = await client.search.searchAgents({ q: 'transformer' });

// 导出
const exportResult = await client.exportModule.agent(agentId, { format: 'json' });
API Reference - NvwaX | NvwaX