跳转到主要内容

​
Base URL

默认情况下，NekoHub API 运行在： 
http://your-host:5121
管理接口统一以 /api/v1/ 为前缀。

​
响应格式

​
成功响应

成功返回统一使用 data 包装： 
{
  "data": {}
}

​
错误响应

错误返回统一使用 error 包装： 
{
  "error": {
    "code": "asset_not_found",
    "message": "Asset with the given ID does not exist.",
    "traceId": "00-abc123...",
    "status": 404
  }
}
字段说明
code机器可读错误码
message人类可读错误信息
traceId便于关联后端日志的请求 ID
statusHTTP 状态码

​
鉴权方式

管理接口支持两类 Bearer：
方式Header场景
JWTAuthorization: Bearer <access_token>浏览器、用户会话
API keyAuthorization: Bearer <api_key>脚本、自动化、MCP
公开接口不需要鉴权。详见 API 鉴权。

​
API 版本

当前版本是 v1。

​
接口分组

分组Base path说明
公开资产/api/v1/public/assets匿名浏览公开资产
资产/api/v1/assets上传、查询、修改、删除资产，运行技能
认证/api/v1/auth登录、刷新、登出、当前用户
用户/api/v1/users用户、状态、密码、权限管理
存储 Provider/api/v1/system/storage管理 storage profiles
AI Provider/api/v1/system/ai/providers管理 AI provider profiles
MCP/mcp提供给 Agent 的 MCP 接口

​
无需鉴权的接口

  • GET /api/v1/system/ping
  • GET /api/v1/system/bootstrap
  • GET /api/v1/public/assets
  • GET /api/v1/public/assets/{id}
  • GET /content/{storageKey}
  • POST /api/v1/auth/login
  • POST /api/v1/auth/refresh