IMA笔记 API

⚠️ 必读约束

🔒 认证

所有请求必须携带 Header：

ima-openapi-clientid: {IMA_OPENAPI_CLIENTID}
ima-openapi-apikey: {IMA_OPENAPI_APIKEY}
Content-Type: application/json

🔒 安全规则

• 笔记属于用户隐私，不要在群聊中主动展示笔记内容。
• 仅响应授权用户的笔记操作请求。

---

快速决策

用户意图	接口别名
「搜索笔记」「找包含XX的笔记」	/openapi/note/v1/search_note_book
「列出笔记本」「有哪些笔记本」	/openapi/note/v1/list_note_folder_by_cursor
「查看XX笔记本里的笔记」	/openapi/note/v1/list_note_by_folder_id
「从markdown新建笔记」「导入笔记」「创建笔记」「生成笔记」	/openapi/note/v1/import_doc
「追加内容到笔记」「在笔记末尾添加」	/openapi/note/v1/append_doc
「获取笔记纯文本」「读取笔记内容」	/openapi/note/v1/get_doc_content

---

数据结构

---

DocBasicInfo

字段	类型	说明
basic_info	DocBasic	见 [DocBasic](#docbasic)

---

DocBasic

字段	类型	说明
docid	string	文章 id
title	string	标题
summary	string	简介
create_time	int64
modify_time	int64
status	DocStatus	文章状态，0=正常，1=已删除
folder_id	string	文件夹 id
folder_name	string	文件夹名称
summary_style	map\<string, string\>	简介样式

---

FolderItem（笔记本条目）

list_note_folder_by_cursor 返回的笔记本对象，字段如下：

字段	类型	说明
folder_id	string	笔记本唯一 ID
name	string	笔记本名称
note_number	int64	笔记本内笔记数量
create_time	int64	创建时间（Unix 毫秒）
modify_time	int64	修改时间（Unix 毫秒）
parent_folder_id	string	上级笔记本 ID（支持嵌套）
folder_type	int	类型：0=用户自建，1=全部笔记，2=未分类
status	int	状态：0=正常，1=已删除

---

QueryInfo

字段	类型	说明
title	string	标题 query
content	string	正文 query

---

SearchedDoc

字段	类型	说明
doc	DocBasicInfo	笔记 basic 数据，见 [DocBasicInfo](#docbasicinfo)
highlight_info	map\<string, string\>	该条笔记匹配的高亮词，key: doc_title（文档标题），value: 包含 <em>高亮词</em> 的字段值

---

NoteBookFolder

字段	类型	说明
folder	NoteBookFolderBasicInfo	笔记本信息，非笔记本为空，见 [NoteBookFolderBasicInfo](#notebookfolderbasicinfo)

---

NoteBookFolderBasicInfo

字段	类型	说明
basic_info	NoteBookFolderBasic	见 [NoteBookFolderBasic](#notebookfolderbasic)

---

NoteBookFolderBasic

字段	类型	说明
folder_id	string	文件夹 id
name	string	笔记本名称
status	DocStatus	笔记本状态，0=正常，1=已删除
create_time	int64	创建时间
modify_time	int64	修改时间
note_number	int64	笔记数量
folder_type	FolderType	文件夹类型：0=用户自建，1=全部笔记，2=未分类

---

NoteBookInfo

字段	类型	说明
basic_info	DocBasicInfo	笔记基础信息，见 [DocBasicInfo](#docbasicinfo)

---

接口详情

1. 搜索笔记

POST /openapi/note/v1/search_note_book

触发场景：用户说「搜索」「找笔记」「查找包含XX的内容」

请求参数

字段	类型	必填	说明
search_type	SearchType	否	检索方式，默认为标题，0=标题，1=正文
sort_type	SortType	否	排序方式，默认为更新时间，0=更新时间，1=创建时间，2=标题，3=大小
query_info	QueryInfo	否	用户 query，见 [QueryInfo](#queryinfo)
start	int64	是	翻页字段
end	int64	是	翻页字段
query_id	string	否	queryid

返回字段

字段	类型	说明
docs	SearchedDoc[]	检索到的笔记 list，见 [SearchedDoc](#searcheddoc)
is_end	bool	是否为最后一批数据
total_hit_num	int64	检索命中结果总数

---

2. 列出笔记本

POST /openapi/note/v1/list_note_folder_by_cursor

触发场景：用户说「列出笔记本」「有哪些分类」「查看笔记本目录」

请求参数

字段	类型	必填	说明
cursor	string	是	游标，第一页传 "0"，后续传后台返回的值
limit	uint64	是	获取笔记数量限制

返回字段

字段	类型	说明
note_book_folders	NoteBookFolder[]	见 [NoteBookFolder](#notebookfolder)
next_cursor	string	下次请求的起始游标
is_end	bool	是否为最后一批数据

---

3. 按笔记本拉取笔记列表

POST /openapi/note/v1/list_note_by_folder_id

触发场景：用户说「查看XX笔记本的笔记」「列出这个笔记本里的内容」

全部笔记根目录的 folder_id 为 user_list_{userid}，可从「列出笔记本」返回的 folder_id 获取。

请求参数

字段	类型	必填	说明
folder_id	string	否	笔记本 ID，根目录为空
cursor	string	是	当前游标，首次传空字符串 ""
limit	uint64	是	获取笔记数量限制

返回字段

字段	类型	说明
note_book_list	NoteBookInfo[]	见 [NoteBookInfo](#notebookinfo)
next_cursor	string	下次请求的起始游标
is_end	bool	是否为最后一批数据

---

4. 从 Markdown 新建笔记

POST /openapi/note/v1/import_doc

触发场景：用户说「从 Markdown 新建笔记」「导入笔记」「把这段 Markdown 保存为笔记」

请求参数

字段	类型	必填	说明
content_format	int	是	文本类型：1=Markdown（默认）目前仅支持 MARKDOWN（值为 1）
content	string	是	笔记正文内容, 只支持markdown格式
folder_id	string	否	关联的笔记本id

返回字段

字段	类型	说明
doc_id	string	新doc的唯一ID

---

5. 追加内容到笔记

POST /openapi/note/v1/append_doc

触发场景：用户说「在这篇笔记末尾追加内容」「把 XX 添加到笔记里」

⚠️ 敏感操作：追加会不可撤销地修改已有笔记。如果用户没有明确指定目标笔记（提供 doc_id 或笔记标题），必须先向用户确认目标笔记，不得自行猜测。模糊场景应优先建议用户使用 import_doc 新建笔记。

请求参数

字段	类型	必填	说明
doc_id	string	是	目标笔记的唯一ID, 需要是本人的笔记
content_format	int	是	文本类型：1=Markdown（默认）目前仅支持 MARKDOWN（值为 1）
content	string	是	要追加的文本内容, 只支持markdown格式

返回字段

字段	类型	说明
doc_id	string	目标笔记的唯一ID

---

6. 获取笔记纯文本

POST /openapi/note/v1/get_doc_content

触发场景：用户说「读取笔记内容」「获取这篇笔记的纯文本」「把笔记转成 Markdown」

请求参数

字段	类型	必填	说明
doc_id	string	是	目标笔记的唯一 ID, 需要是本人的笔记
target_content_format	int	是	目标文本类型：0=纯文本（推荐），1=Markdown（不支持），2=JSON

返回字段

字段	类型	说明
content	string	笔记的文本内容（按 target_content_format 格式返回）

---

枚举值

sort_type（排序方式）

值	说明
0	更新时间（默认）
1	创建时间
2	标题
3	大小

search_type（检索方式）

值	说明
0	标题检索（默认）
1	正文检索

content_format（文本类型）

值	说明
0	PLAINTEXT - 纯文本
1	MARKDOWN - Markdown 格式
2	JSON - JSON 格式

FolderType

值	说明
0	用户自建
1	全部笔记
2	未分类

---

游标翻页使用规范

1. 首次请求：cursor 传空字符串 ""
2. 检查返回的 is_end：false 表示还有更多数据
3. 将返回的 next_cursor 作为下次请求的 cursor
4. is_end = true 时停止翻页

---

错误码

错误码	说明
0	成功
100001	参数错误
100002	携带无效的 ID
100003	服务器内部错误
100004	拉取的 size 不合法（超出范围）/ 用户空间不够
100005	不能获取私有笔记的访客信息 / 不是笔记的作者
100006	笔记已被删除
100008	版本冲突
100009	单篇笔记超过最大限制
310001	笔记本不存在
20002	apiKey超过最大限频
20004	apikey鉴权失败