tiantian-system/public/docs/api-reference.md

REST API 完整参考

200+ 标准接口文档，覆盖用户、内容、AI、支付等全部模块。

📚 API 概览

基础 URL： https://api.websopy.com/v1

认证方式： Bearer Token

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.websopy.com/v1/user/profile

📋 端点列表

用户管理 /user

方法	端点	说明
GET	/user/profile	获取当前用户信息
PUT	/user/profile	更新用户信息
GET	/user/settings	获取用户设置
PUT	/user/settings	更新用户设置
POST	/user/avatar	上传头像

项目管理 /projects

方法	端点	说明
GET	/projects	列出项目
POST	/projects	创建项目
GET	/projects/:id	获取项目详情
PUT	/projects/:id	更新项目
DELETE	/projects/:id	删除项目
GET	/projects/:id/members	获取项目成员
POST	/projects/:id/members	添加成员

文件存储 /storage

方法	端点	说明
GET	/storage/files	列出文件
POST	/storage/upload	上传文件
GET	/storage/files/:id	获取文件信息
DELETE	/storage/files/:id	删除文件
GET	/storage/files/:id/download	下载文件

AI 功能 /ai

方法	端点	说明
POST	/ai/chat	发送对话请求
POST	/ai/chat/stream	流式对话
GET	/ai/sessions	列出会话
POST	/ai/sessions	创建会话
GET	/ai/sessions/:id	获取会话详情
DELETE	/ai/sessions/:id	删除会话
POST	/ai/knowledge	创建知识库
POST	/ai/knowledge/:id/documents	添加文档

支付 /payments

方法	端点	说明
GET	/payments/orders	列出订单
POST	/payments/orders	创建订单
GET	/payments/orders/:id	订单详情
POST	/payments/checkout	创建结算会话
GET	/payments/subscriptions	订阅列表

🔍 请求与响应

请求头

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json
X-Request-ID: unique-request-id

分页

GET /projects?page=2&limit=20

响应包含分页信息：

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "total": 100,
    "total_pages": 5
  }
}

排序

GET /projects?sort=created_at&order=desc

过滤

GET /projects?status=active&category=ai

📝 错误处理

错误码

状态码	错误码	说明
400	INVALID_REQUEST	请求参数错误
401	UNAUTHORIZED	未认证或 Token 无效
403	FORBIDDEN	无权限访问
404	NOT_FOUND	资源不存在
429	RATE_LIMITED	请求过于频繁
500	SERVER_ERROR	服务器内部错误

错误响应格式

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "参数 'name' 不能为空",
    "details": {
      "field": "name",
      "constraint": "required"
    }
  }
}

🔧 使用示例

JavaScript/TypeScript

const response = await fetch('https://api.websopy.com/v1/projects', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '我的项目',
    description: '项目描述'
  })
})

const data = await response.json()
console.log(data)

Python

import requests

response = requests.post(
    'https://api.websopy.com/v1/projects',
    headers={
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    },
    json={
        'name': '我的项目',
        'description': '项目描述'
    }
)

data = response.json()
print(data)

---

上一步： Webhook 事件接入
下一步： RAG 知识库搭建