列出¶

POST /api/v1/notes_v2/list

概述¶

列出当前 API Key 所属账号可见的新版笔记。

Body 请求参数¶

参数名	类型	必选	说明
pageIndex	integer		页码允许为空: False
pageSize	integer		每页数量允许为空: False
search	string		标题和正文搜索词允许为空: False
query	string		标题和正文搜索词，优先级高于 search 允许为空: False
tags	array		全局标签过滤，传多个标签时默认 OR 命中允许为空: False
tagKV	json		键值标签过滤，例如 {"host":"127.0.0.1"} 允许为空: False
tagKVQuery	string		键值标签表达式过滤，例如 host:"127.0.0.1" 允许为空: False
tagMode	string		标签匹配方式，不传时 tags 默认按 or 匹配允许为空: False 可选值: ['and', 'or']
createdSource	string		创建来源过滤，例如 manual 或 ai 允许为空: False
noteType	string		笔记类型过滤，normal 为普通笔记，runbook 为操作手册允许为空: False 可选值: ['normal', 'runbook']
isPublic	boolean		是否只返回公开或私有笔记；Status Page 应固定传 true 允许为空: False
tagKVRange	json		TagKV 字符串闭区间过滤，例如 {"date":{"gte":"2026-05-03","lte":"2026-07-31"}} 允许为空: False
includeContent	boolean		是否在列表项中返回 Markdown content；开启时必须分页且 pageSize 不超过 100 允许为空: False

参数补充说明¶

使用该接口获取当前工作空间下当前 API Key 可访问的新版笔记摘要。

需要分页时同时传 pageIndex 和 pageSize。
需要按标题或正文搜索时传 search，也可以传 query；两者同时存在时以 query 为准。
需要按标签过滤时传 tags、tagKV 或 tagKVQuery，例如 tagKVQuery: "host:\"127.0.0.1\""；tags 传多个值且不传 tagMode 时按 OR 命中。
列表响应不包含 Markdown 正文，读取正文请调用详情接口。
后续获取、修改、删除都使用响应里的 noteUUID。

请求例子¶

curl 'https://openapi.guance.com/api/v1/notes_v2/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"pageIndex":1,"pageSize":20,"isPublic":true,"includeContent":true,"tagKV":{"page_scope":"status_page","publish_status":"published"},"tagKVRange":{"date":{"gte":"2026-05-03","lte":"2026-07-31"}}}'

响应¶

{
    "code": 200,
    "content": {
        "data": [
            {
                "noteUUID": "nbnote_xxx",
                "title": "A",
                "name": "A",
                "tags": [
                    "ops"
                ],
                "tagKV": {
                    "host": "127.0.0.1"
                },
                "isPublic": 1,
                "createdSource": "manual",
                "noteType": "normal",
                "etag": "etag_xxx",
                "version": 1,
                "createAt": 1782370000,
                "updateAt": 1782370100
            }
        ],
        "pageInfo": {
            "pageIndex": 1,
            "pageSize": 20,
            "totalCount": 1
        }
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-XXXX"
}