NetSeed Docs

API 参考

面向客户自动化的稳定 NSD 管理 API。当前参考完整覆盖所有公开支持的操作、参数、请求体、成功响应字段、JSON 示例和错误状态。

下载 OpenAPI 3.1 JSON · 创建和管理 API 令牌 · Webhook 验签与重试

接口目录

分组操作数范围
身份与用户3验证令牌上下文，并读取当前 Network 中的用户。
节点、服务与网关7读取节点、服务和网关运行信息，并维护允许编辑的服务元数据。
用户组与访问授权14维护用户组、组成员和访问授权；写操作需要 full 令牌。
子网路由与运行数据5读取或维护子网路由，并查询用量和活动日志。
Webhook API6维护 Webhook 订阅、发送测试事件，并读取投递结果。

当前共 35 个受支持操作。请使用本参考和 OpenAPI 文件中列出的接口。

通用约定

  • 根地址：https://<nsd-host>/api/v1。
  • 鉴权：Authorization: Bearer $NSD_TOKEN。令牌是 nsda_ 开头的不透明值。
  • 内容：请求和成功响应使用 JSON；无返回内容的成功操作使用 204 No Content。
  • 时间：RFC 3339 UTC；用量筛选中的 from、to 使用 Unix 秒。
  • 分页：有 next_cursor 时，把它原样作为下一页 cursor；不要解析游标。
  • 权限：read-only 只允许 GET/HEAD/OPTIONS；修改操作需要 full，且创建令牌的管理员仍须有效。

错误响应

所有错误使用 application/problem+json。每个接口页面列出该操作明确声明的错误状态；此外，鉴权中间件可能统一返回 401、403，限流可能返回 429。

字段类型含义
typestring稳定的问题类型 URI
titlestring简短错误类别
statusintegerHTTP 状态码
detailstring本次错误的可读说明，文案可能优化
instancestring | null相关请求路径（如有）
codestring稳定、可供程序判断的错误码
{
  "type": "https://nsiod.dev/problems/auth.token_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "this API token scope does not allow the requested operation",
  "instance": "/api/v1/policies",
  "code": "auth.token_scope"
}
状态处理方式
400修正参数或请求体，不要原样重试
401令牌缺失、无效、过期或已吊销；更换令牌
403令牌 scope 或当前用户角色不足
404资源不存在，或不属于当前 Network
409与当前状态冲突；重新读取资源后决定是否重试
429遵循 Retry-After，使用带抖动的指数退避
5xx记录请求 ID；仅对幂等请求自动重试

安全边界

调用管理接口需要有效令牌及相应权限。操作前确认令牌所属 Network，按任务授予最小权限。示例数据不可直接用于真实请求；不要将令牌粘贴到第三方调试页面或公开日志中。

返回 API 访问与令牌管理。