{ "openapi": "3.1.0", "info": { "title": "枝记外部笔记 API", "version": "1.0.0", "description": "标准HTTP JSON接口，独立可撤销Bearer凭据。读取、新增、追加分别授权。无日历/删除/全篇覆盖。" }, "servers": [ { "url": "https://zj.qingfengzm.site" } ], "paths": { "/api/external/v1/search": { "post": { "operationId": "search_notes", "summary": "在当前账号获授权的全部云端笔记中搜索标题及正文；只返回有界摘要。续页使用首页 sequence。", "security": [ { "externalToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "offset": { "type": "integer", "minimum": 0, "maximum": 10000, "default": 0 }, "expectedSequence": { "type": "integer", "minimum": 0 } }, "required": [ "query", "limit", "offset" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "成功；字段见接口说明", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "maxItems": 50, "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string", "maxLength": 200 }, "contentRevision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "title", "summary", "contentRevision" ], "additionalProperties": false } }, "sequence": { "type": "integer", "minimum": 0 }, "nextOffset": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "items", "sequence", "nextOffset" ], "additionalProperties": false } } } }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "授权无效、过期或已撤销", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "缺少对应权限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "笔记或操作不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "版本冲突或同一requestId输入不一致", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "容量已满或请求超过64KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "操作频率超限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "服务暂不可用；写入结果不明先查询原requestId", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/external/v1/get": { "post": { "operationId": "get_note", "summary": "读取指定云端笔记的文字节点和版本，不返回附件。", "security": [ { "externalToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "documentId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "成功；字段见接口说明", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "contentRevision": { "type": "integer", "minimum": 1 }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "depth": { "type": "integer", "minimum": 0 }, "text": { "type": "string" }, "note": { "type": "string" }, "task": { "type": "boolean" }, "done": { "type": "boolean" } }, "required": [ "id", "depth", "text", "note", "task", "done" ], "additionalProperties": false } }, "updatedAt": { "type": "string" } }, "required": [ "id", "title", "contentRevision", "nodes" ], "additionalProperties": false } } } }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "授权无效、过期或已撤销", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "缺少对应权限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "笔记或操作不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "版本冲突或同一requestId输入不一致", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "容量已满或请求超过64KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "操作频率超限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "服务暂不可用；写入结果不明先查询原requestId", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/external/v1/create": { "post": { "operationId": "create_note", "summary": "向当前账号根目录新增笔记。需新增权限；使用唯一 requestId，结果不明时先 get_operation 查询同一 requestId，禁止改ID盲目重试。", "security": [ { "externalToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" }, "title": { "type": "string", "minLength": 1, "maxLength": 500 }, "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "requestId", "title", "text" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "成功；字段见接口说明", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "contentRevision": { "type": "integer", "minimum": 1 }, "changeSequence": { "type": "integer", "minimum": 0 } }, "required": [ "documentId", "contentRevision", "changeSequence" ], "additionalProperties": false } } } }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "授权无效、过期或已撤销", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "缺少对应权限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "笔记或操作不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "版本冲突或同一requestId输入不一致", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "容量已满或请求超过64KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "操作频率超限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "服务暂不可用；写入结果不明先查询原requestId", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/external/v1/append": { "post": { "operationId": "append_note", "summary": "在指定笔记末尾追加纯文本，不覆盖原内容；需追加权限与最新 contentRevision。冲突时先重新读取。使用唯一 requestId，结果不明先 get_operation 查询。", "security": [ { "externalToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" }, "documentId": { "type": "string", "minLength": 1, "maxLength": 200 }, "expectedContentRevision": { "type": "integer", "minimum": 1 }, "text": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "requestId", "documentId", "expectedContentRevision", "text" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "成功；字段见接口说明", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "contentRevision": { "type": "integer", "minimum": 1 }, "changeSequence": { "type": "integer", "minimum": 0 } }, "required": [ "documentId", "contentRevision", "changeSequence" ], "additionalProperties": false } } } }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "授权无效、过期或已撤销", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "缺少对应权限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "笔记或操作不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "版本冲突或同一requestId输入不一致", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "容量已满或请求超过64KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "操作频率超限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "服务暂不可用；写入结果不明先查询原requestId", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/api/external/v1/operation": { "post": { "operationId": "get_operation", "summary": "查询当前授权凭据下原 requestId 的写入结果或冲突。不会重发写入。", "security": [ { "externalToken": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[a-zA-Z0-9_-]+$" } }, "required": [ "requestId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "成功；字段见接口说明", "content": { "application/json": { "schema": { "type": "object", "properties": { "documentId": { "type": "string" }, "contentRevision": { "type": "integer", "minimum": 1 }, "changeSequence": { "type": "integer", "minimum": 0 } }, "required": [ "documentId", "contentRevision", "changeSequence" ], "additionalProperties": false } } } }, "400": { "description": "参数无效", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "授权无效、过期或已撤销", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "403": { "description": "缺少对应权限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "笔记或操作不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "409": { "description": "版本冲突或同一requestId输入不一致", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "413": { "description": "容量已满或请求超过64KiB", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "429": { "description": "操作频率超限", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "服务暂不可用；写入结果不明先查询原requestId", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "retryable" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } } }, "components": { "securitySchemes": { "externalToken": { "type": "http", "scheme": "bearer", "description": "在枝记设置→外部工具创建；zj_ext_前缀。禁止使用网页登录密码或会话令牌。" } } } }