List¶

POST /api/v1/notes_v2/list

Overview¶

List the new notes visible to the account associated with the current API Key.

Body Request Parameters¶

Parameter	Type	Description
pageIndex	integer	Page number Allow empty: False
pageSize	integer	Number of items per page Allow empty: False
search	string	Search term for title and content Allow empty: False
query	string	Search term for title and content, higher priority than `search` Allow empty: False
tags	array	Global tag filter, multiple tags use OR by default Allow empty: False
tagKV	json	Key-value tag filter, e.g. {"host":"127.0.0.1"} Allow empty: False
tagKVQuery	string	Key-value tag expression filter, e.g. host:"127.0.0.1" Allow empty: False
tagMode	string	Tag matching mode; if not specified, `tags` defaults to `or` Allow empty: False Valid values: ['and', 'or']
createdSource	string	Filter by creation source, e.g. `manual` or `ai` Allow empty: False
noteType	string	Filter by note type, `normal` for regular notes, `runbook` for runbooks Allow empty: False Valid values: ['normal', 'runbook']
isPublic	boolean	Return only public or private notes; Status Page should always pass `true` Allow empty: False
tagKVRange	json	TagKV closed-interval filter, e.g. {"date":{"gte":"2026-05-03","lte":"2026-07-31"}} Allow empty: False
includeContent	boolean	Whether to include Markdown `content` in list items; when enabled, pagination is required and `pageSize` must not exceed 100 Allow empty: False

Additional Parameter Notes¶

Use this endpoint to retrieve summaries of new notes accessible to the current API Key in the current workspace.

For pagination, pass both pageIndex and pageSize.
To search by title or content, use search or query; when both are present, query takes precedence.
To filter by tags, use tags, tagKV, or tagKVQuery, e.g. tagKVQuery: "host:\"127.0.0.1\""; when multiple tags are passed in tags without tagMode, the default matching is OR.
The list response does not include Markdown content; use the detail endpoint to retrieve the full content.
Subsequent fetch, update, and delete operations use the noteUUID from the response.

Request Example¶

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"}}}'

Response¶

{
    "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"
}