Noolingo API

Noolingo 提供了完整的 API 接口，让你可以连接任何支持的外部应用。所有 API 都遵循 REST 设计原则，使用标准 HTTP 方法和状态码进行交互。

关于 Noolingo API

使用 Noolingo API，你可以：

• 自动化笔记管理：批量创建、修改、删除笔记
• 集成其他工具：将 Noolingo 与你的工作流、脚本或其他应用连接
• 数据分析：导出数据进行分析或生成报告
• 自定义功能：构建符合自己需求的功能

所有 API 请求都使用标准的 HTTP 方法（GET、POST、PUT、DELETE），返回 JSON 格式的数据。

基础信息

基础地址：https://api.noolingo.com/api

认证方式：Bearer Token

请求头：在请求头中添加 Authorization: Bearer your_api_key_here

响应格式：所有响应都是 JSON 格式，使用标准的 HTTP 状态码（200 成功、400 错误请求、401 未授权、404 未找到等）

获取 API 密钥

在使用 API 之前，你需要获取 API 密钥：

1. 登录你的 Noolingo 账户
2. 进入"设置 > 账户设置 > ApiKey"
3. 点击"创建新密钥"生成你的 API 密钥
4. 如果需要刷新密钥（比如怀疑密钥泄露），请点击"刷新密钥"按钮

安全提示：请妥善保管你的 API 密钥，不要将其提交到代码仓库或公开分享。如果密钥泄露，请立即刷新密钥。

获取笔记列表

获取你的笔记列表，支持分页和筛选。

HTTP 方法：GET

路径：/notes/

查询参数：

示例请求：

GET /notes/?limit=50&offset=100&deck_id=abc123
Authorization: Bearer your_api_key_here

响应示例：

{
  "data": [
    {
      "id": "note-id-1",
      "title": "笔记标题",
      "markdown_text": "笔记内容",
      "tags": ["标签1", "标签2"],
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 100,
  "limit": 50,
  "offset": 100
}

获取单个笔记

获取指定笔记的详细信息。

HTTP 方法：GET

路径：/notes/:note_id

路径参数：note_id - 笔记的唯一标识符

示例请求：

GET /notes/499b224a-e51e-4f9e-928a-cac7a66dbc4d
Authorization: Bearer your_api_key_here

响应示例：

{
  "id": "499b224a-e51e-4f9e-928a-cac7a66dbc4d",
  "title": "笔记标题",
  "markdown_text": "笔记的 Markdown 内容",
  "tags": ["标签1", "标签2"],
  "deck_id": "笔记本ID",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

创建笔记

创建一篇新笔记。

HTTP 方法：POST

路径：/notes/?deck_id=xx

查询参数：deck_id（可选）- 指定笔记所属的笔记本 ID。如果不提供，笔记会创建在默认笔记本中。

请求体：

重要提示：Noolingo 的核心存储格式是 Markdown，因此 API 只接受 markdown_text 字段。请务必使用 Markdown 格式提交笔记内容。旧的 html_text 字段已不再支持，使用它可能导致笔记内容无法正确读取。

示例请求：

POST /notes/?deck_id=abc123
Authorization: Bearer your_api_key_here
Content-Type: application/json

{
  "title": "新笔记",
  "markdown_text": "这是笔记内容\n\n**重点内容**",
  "tags": ["学习", "重要"]
}

响应示例：

{
  "id": "新创建的笔记ID",
  "title": "新笔记",
  "markdown_text": "这是笔记内容\n\n**重点内容**",
  "tags": ["学习", "重要"],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

更新笔记

更新已存在的笔记。

HTTP 方法：PUT

路径：/notes/:note_id

路径参数：note_id - 要更新的笔记 ID

请求体：

注意：所有字段都是可选的，只需要提供要更新的字段即可。未提供的字段将保持原有值。

重要提示：请使用 markdown_text 字段更新笔记内容。html_text 字段已不再支持，使用它可能导致笔记内容无法正确读取。

示例请求：

PUT /notes/499b224a-e51e-4f9e-928a-cac7a66dbc4d
Authorization: Bearer your_api_key_here
Content-Type: application/json

{
  "title": "更新后的标题",
  "tags": ["新标签"]
}

错误处理

API 使用标准的 HTTP 状态码来表示请求结果：

• 200 OK：请求成功
• 400 Bad Request：请求参数错误
• 401 Unauthorized：认证失败，API 密钥无效
• 404 Not Found：请求的资源不存在
• 500 Internal Server Error：服务器内部错误

错误响应会包含错误信息：

{
  "error": "错误描述",
  "code": "错误代码"
}

使用建议

频率限制：为了保障服务稳定性，API 请求有频率限制。请合理控制请求频率，避免过于频繁的请求。

数据格式：必须使用 Markdown 格式提交内容。Noolingo 的核心存储格式是 Markdown，API 只接受 markdown_text 字段。请勿使用 html_text 字段，它已不再支持，可能导致笔记内容无法正确读取。如果你有 HTML 内容，请先转换为 Markdown 格式再提交。

批量操作：如果需要批量创建或更新笔记，建议分批处理，每批不超过 100 条，避免单次请求过大。

错误重试：如果请求失败，可以检查错误信息并适当重试。对于网络错误，建议实现指数退避的重试策略。

Noolingo API 为你提供了灵活的数据访问方式，让你可以根据自己的需求定制工作流。