个人服务API文档

面向个人服务平台的开放接口说明，覆盖身份认证、账户资料、内容检索、文件访问凭证和消息偏好配置。接口统一使用 JSON 作为请求与响应格式，认证接口以外的资源接口均通过 Bearer Token 访问。

版本 v1.2.0

基础地址 https://saberdance.cc

响应格式 application/json

认证方式 Bearer Token

账户认证

用于完成用户登录、令牌刷新和会话退出。登录成功后返回访问令牌与刷新令牌。

Authentication

POST /api/v1/auth/login 账户登录

使用账户名和密码换取访问令牌。访问令牌用于后续接口调用，刷新令牌用于延长会话有效期。

参数	位置	类型	说明
`username`	body	string	登录账户名或已绑定手机号。
`password`	body	string	账户登录密码。
`clientId`	body	string	客户端标识，用于会话管理。

请求示例JSON

{
  "username": "service_user",
  "password": "********",
  "clientId": "web-console"
}

响应示例200 OK

{
  "code": 0,
  "message": "success",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "e4a8c7f9b2...",
    "expiresIn": 7200
  }
}

POST /api/v1/auth/refresh 刷新令牌

使用刷新令牌获取新的访问令牌。刷新成功后旧访问令牌自动失效。

请求示例JSON

{
  "refreshToken": "e4a8c7f9b2..."
}

响应示例200 OK

{
  "code": 0,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 7200
  }
}

账户资料

查询和更新当前登录账户的基础资料、联系信息与服务偏好。

Account

GET /api/v1/account/profile 获取账户资料

返回当前账户的公开资料、绑定状态和最近登录时间。该接口需要携带有效访问令牌。

请求头	类型	必填	说明
`Authorization`	string	是	格式为 `Bearer access_token`。

cURLGET

curl -H "Authorization: Bearer ${TOKEN}" \
  https://saberdance.cc/api/v1/account/profile

响应示例200 OK

{
  "code": 0,
  "data": {
    "accountId": "acct_10086",
    "displayName": "个人服务用户",
    "emailVerified": true,
    "lastLoginAt": "2026-06-30T09:16:20+08:00"
  }
}

PUT /api/v1/account/profile 更新账户资料

更新当前账户的展示名称、联系邮箱和区域设置。未提交的字段保持不变。

请求示例JSON

{
  "displayName": "个人服务用户",
  "email": "user@example.com",
  "timezone": "Asia/Shanghai"
}

响应示例200 OK

{
  "code": 0,
  "message": "profile updated"
}

内容服务

提供内容列表、详情查询和关键词检索能力，适用于个人服务内容的统一读取。

Content

GET /api/v1/content/items 获取内容列表

按分页条件返回当前账户可访问的内容条目。支持根据分类、更新时间和状态进行筛选。

参数	位置	类型	说明
`page`	query	integer	页码，从 1 开始。
`pageSize`	query	integer	每页数量，默认 20，最大 100。
`category`	query	string	内容分类标识。

请求示例GET

GET /api/v1/content/items?page=1&pageSize=20&category=article

响应示例200 OK

{
  "code": 0,
  "data": {
    "total": 48,
    "items": [
      {
        "contentId": "cnt_240630001",
        "title": "服务更新说明",
        "category": "article",
        "updatedAt": "2026-06-30T08:30:00+08:00"
      }
    ]
  }
}

GET /api/v1/content/items/{contentId} 获取内容详情

根据内容编号读取标题、正文摘要、附件信息和访问权限。不存在或无权限的内容将返回标准错误码。

路径参数contentId

{
  "contentId": "cnt_240630001"
}

响应示例200 OK

{
  "code": 0,
  "data": {
    "contentId": "cnt_240630001",
    "title": "服务更新说明",
    "summary": "本次更新优化了账户资料与内容检索能力。",
    "attachments": []
  }
}

POST /api/v1/content/search 搜索内容

按关键词、分类和时间范围进行内容搜索，返回匹配度排序后的分页结果。

请求示例JSON

{
  "keyword": "服务",
  "category": "article",
  "from": "2026-01-01",
  "to": "2026-06-30"
}

响应示例200 OK

{
  "code": 0,
  "data": {
    "total": 12,
    "items": []
  }
}

文件凭证

按权限签发临时上传或下载凭证，便于客户端安全访问文件资源。

File

POST /api/v1/files/upload-token 获取上传凭证

申请指定文件类型和大小范围内的上传凭证。凭证有效期较短，请在返回后尽快使用。

请求示例JSON

{
  "fileName": "document.pdf",
  "contentType": "application/pdf",
  "size": 204800
}

响应示例200 OK

{
  "code": 0,
  "data": {
    "uploadUrl": "https://saberdance.cc/api/v1/files/upload",
    "token": "up_7d8f9a...",
    "expiresIn": 900
  }
}

消息设置

读取和保存账户的消息通知偏好，包括系统通知、内容更新和安全提醒。

Notification

PATCH /api/v1/notifications/preferences 更新消息偏好

修改当前账户的通知接收方式。接口支持局部更新，未提交字段不会被覆盖。

请求示例JSON

{
  "system": true,
  "content": true,
  "security": true,
  "channels": ["email"]
}

响应示例200 OK

{
  "code": 0,
  "message": "preferences saved"
}

系统状态

用于检查服务基础状态和接口版本信息，便于客户端判断服务可用性。

System

GET /api/v1/system/health 健康检查

返回服务状态、当前版本和服务器时间。该接口不需要账户授权。

请求示例GET

GET /api/v1/system/health

响应示例200 OK

{
  "code": 0,
  "data": {
    "status": "healthy",
    "version": "v1.2.0",
    "timestamp": "2026-06-30T10:30:00+08:00"
  }
}