API 参考

Knoself 提供 REST API，方便开发者集成和扩展功能。

基础信息

Base URL

https://knoself.com/api

认证

所有受保护的 API 需要在请求头中包含 JWT Token：

Authorization: Bearer YOUR_TOKEN_HERE

响应格式

所有 API 返回 JSON 格式数据：

{
  "status": "success",
  "data": { ... }
}

认证 API

登录

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password"
}

响应:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "123",
    "email": "user@example.com"
  }
}

注册

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your_password",
  "name": "Your Name"
}

用户 API

获取用户资料

GET /api/user/profile
Authorization: Bearer YOUR_TOKEN

响应:

{
  "user": {
    "id": "123",
    "email": "user@example.com",
    "name": "Your Name"
  }
}

同步 API

数据同步

POST /api/sync
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "device_id": "device_123",
  "timestamp": 1706626800,
  "data": {
    "notes": [...],
    "tags": [...]
  }
}

响应:

{
  "status": "success",
  "message": "data synced successfully",
  "synced_items": 10
}

错误处理

错误响应格式

{
  "error": "error message here"
}

常见错误码

状态码	说明
400	请求参数错误
401	未授权（token 无效或过期）
403	禁止访问
404	资源不存在
429	请求过于频繁
500	服务器错误

速率限制

• 每个 IP 每分钟最多 100 个请求
• 超出限制返回 429 Too Many Requests

SDK 和示例

JavaScript/TypeScript

// 使用 fetch API
const response = await fetch('https://knoself.com/api/user/profile', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
});

const data = await response.json();

Python

import requests

headers = {
    'Authorization': f'Bearer {token}',
    'Content-Type': 'application/json',
}

response = requests.get(
    'https://knoself.com/api/user/profile',
    headers=headers
)

data = response.json()

更多资源

• 同步指南 - 了解同步机制
• 安全最佳实践 - API 安全建议