Noolingo 的外部 API 操作当前账户的云端笔记。未同步的本地笔记不会出现在 API 中。
基础地址：https://api.noolingo.com/api。在应用的账户设置中创建或刷新 API Key，请求头使用 Authorization: Bearer YOUR_API_KEY。刷新会替换旧密钥；不要把密钥放进 URL、聊天、公开代码或插件包。
API Key 是账户级凭证，允许读写和删除笔记。第三方应用可使用下文的 OAuth 授权，不要求用户交出账户 API Key。
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /me | 账户信息，包含邮箱、手机号和权益；仅在确有需要时调用 |
| GET | /notes | 按更新时间降序列出笔记 |
| GET | /notes/:noteId | 读取属于当前账户的笔记 |
| POST | /notes | 创建笔记，禁止提供 id、_id 或 noteId |
| PUT | /notes/:noteId | 更新指定字段，不允许更改 id |
| DELETE | /notes/:noteId | 永久删除笔记 |
列表参数：limit 默认 20，范围 1–1000；offset 默认 0，范围 0–100000；可选 deck_id 和 tag 精确筛选。没有全文搜索。列表响应为 { "success": true, "data": [...] }，不包含 total；按实际返回条数推进 offset，空页表示结束。并发编辑时 offset 分页可能重复或跳过笔记。
创建和更新字段：
| 字段 | 说明 |
|---|---|
| title | 可选字符串，最多 300 字符 |
| markdown_text | 推荐正文格式，最多 50000 字符 |
| html_text | 兼容旧数据的 HTML 正文，最多 50000 字符；新集成使用 Markdown |
| tags | 最多 20 个标签，每个 1–100 字符 |
| deck_id | 可选、属于当前账户的笔记本 ID；创建时未指定则为 null |
| priority | 可选整数，0–100 |
| recall | 兼容旧客户端的数值字段；不是复习评分 API |
创建必须有非空正文；更新可只提交标签等字段。也可通过 ?deck_id=... 指定笔记本，查询参数优先。创建 null deck 的笔记不等于自动新建笔记本。创建、更新和删除会进入现有同步变更记录。
POST /api/notes
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
{"title":"主动回忆","markdown_text":"{{主动回忆}}有助于强化长期记忆。","tags":["学习"]}
单篇和创建响应示例：
{"success":true,"data":{"id":"note-id","title":"主动回忆","markdown_text":"{{主动回忆}}有助于强化长期记忆。","tags":["学习"],"deck_id":null,"created_at":1792368000000,"updated_at":1792368000000}}
时间戳为 epoch 毫秒。可选字段仅在数据中存在时返回。创建返回 201，读取/更新/删除返回 200。失败格式为 { "success": false, "message": "ERROR_CODE" }；401 为凭证失效，404 为笔记不存在，400 为业务或参数错误，413 为请求过大，429 为限流，500 为系统错误。请求体上限为 128 KiB，当前单进程 REST 入口按来源每分钟最多 300 次请求；共享出口会共用该预算。创建还受账户云笔记配额约束。
更新/创建出现 INVALID_NOTE、INVALID_QUERY、DECK_NOT_FOUND 或 CLOUD_NOTE_QUOTA_EXCEEDED 时，应修正参数或提示用户。创建时可添加 Idempotency-Key 请求头（16–128 位字母、数字、下划线或连字符）。重试必须复用相同键和内容；相同键不同内容返回 IDEMPOTENCY_CONFLICT。未提供幂等键时，不要盲目自动重试创建。
OAuth 直接授权上述 REST API，与 API Key 并存。第三方应用必须先由维护者登记客户端，不提供开放动态注册。请联系 [email protected]，提供应用名称、精确 HTTPS 回调地址和所需权限。
| 权限 | 允许的操作 |
|---|---|
| notes:read | GET /notes 和 /notes/:noteId |
| notes:create | POST /notes |
| notes:update | PUT /notes/:noteId |
| notes:delete | DELETE /notes/:noteId，永久删除 |
| profile:read | GET /me，包含邮箱、手机号等账户资料 |
申请最少权限。API Key 仍为账户级权限；OAuth 令牌只能执行用户批准的操作。权限不足返回 403 OAUTH_INSUFFICIENT_SCOPE，令牌无效或授权被撤销返回 401 OAUTH_TOKEN_INVALID。
https://api.noolingo.com/.well-known/oauth-authorization-serverhttps://api.noolingo.com/.well-known/oauth-protected-resource/apihttps://api.noolingo.com/api/oauth/authorize；令牌端点：/oauth/token；撤销端点：/oauth/revoke目前支持预注册 public client，令牌端点鉴权方式 none。必须使用授权码 + PKCE S256，不支持 implicit、client_credentials 或固定 API Key 换取 OAuth token。客户端 ID 和回调由维护者登记，不能使用示例值连接生产。
授权请求包含 response_type=code、client_id、精确登记的 redirect_uri、resource、以空格分隔的 scope、state、code_challenge 和 code_challenge_method=S256。用户在 Noolingo 登录后，核对应用名称和权限并明确批准。客户端必须验证回调中的 state 和 iss。
授权码 5 分钟内有效且只能兑换一次。令牌兑换以 application/x-www-form-urlencoded POST 提交 grant_type=authorization_code、code、client_id、redirect_uri、resource 和 code_verifier。成功响应包含 access_token、refresh_token、token_type=Bearer、expires_in=3600 和 scope。
API 调用使用 Authorization: Bearer ACCESS_TOKEN，不能将 access token 放入 URL。授权最长有效 30 天；access token 有效 1 小时。刷新时提交 grant_type=refresh_token、refresh_token、client_id、resource；可附加更小范围的 scope。刷新令牌每次轮换，重放已使用的刷新令牌会撤销整个授权，客户端应避免并行刷新。
撤销时 POST /oauth/revoke，表单包含 token（access 或 refresh token）和 client_id。用户也可在已连接的应用查看和撤销授权。撤销停止后续访问，不删除已有笔记，也不撤回第三方已接收的数据。
开发示例、错误处理与配置说明见 OAuth 接入指南。参阅隐私政策和服务条款。