2026/9/12 2:49:59
FEATURED · 精选文章 
Karakeep SDK 使用指南用 TypeScript 客户端操作自托管书签 API【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder导读Karakeep原 Hoarder是一款自托管收藏一切应用支持链接、笔记和图片并提供基于 AI 的自动标签与全文搜索。karakeep/sdk是官方 TypeScript SDK基于openapi-fetch与自动生成的 OpenAPI 类型封装 REST 接口让你在几行代码内完成书签创建、检索、搜索、列表与标签管理等操作。读完本文你将掌握 SDK 的安装方式、客户端初始化、典型增删改查与搜索调用以及其版本策略与类型安全背后的实现原理。一、SDK 是什么从源码看它的真实构成karakeep/sdk包位于 packages/sdk其核心入口 src/index.ts 只有短短十几行却揭示了这个 SDK 的设计哲学——它不是一个臃肿的封装层而是直接建立在openapi-fetch之上的薄封装import createClient from openapi-fetch; import type { components, paths } from ./karakeep-api.d.ts; // deprecated Use createKarakeepClient instead. export const createHoarderClient createClientpaths; export const createKarakeepClient createClientpaths; export type KarakeepAPISchemas components[schemas];关键点解读两个客户端工厂createKarakeepClient是推荐入口createHoarderClient是历史遗留的旧名源码中以deprecated标注仅用于向后兼容。类型即文档paths与components来自 src/karakeep-api.d.ts该文件由openapi-typescript从服务端 OpenAPI 规范自动生成文件头注释明确标注 This file was auto-generated by openapi-typescript定义了全部端点路径、请求参数与响应 Schema。零手写请求逻辑所有 HTTP 调用行为fetch、请求/响应类型校验、错误处理全部由openapi-fetch提供SDK 本身只负责接入类型。构建配置方面vite.config.mts 将 SDK 打包为es与cjs双格式index.mjs/index.js并生成类型声明vite-plugin-dts同时把openapi-fetch声明为 external 依赖避免重复打包。这也解释了为什么 SDK 的运行时依赖只有openapi-fetch一个见 package.json。二、安装SDK 以 npm 包形式发布使用任意包管理器安装即可npm install karakeep/sdk提示从 package.json 可以看到main指向./src/index.tsworkspace 内直接使用源码发布时则通过publishConfig指向构建产物./dist/index.js、./dist/index.mjs与./dist/index.d.ts因此安装后同时支持 ESM 与 CommonJS 项目。当前仓库中该包的版本为0.33.0与 Karakeep 服务器次版本号一致详见后文版本策略。三、快速上手创建客户端SDK 使用 Bearer TokenAPI Key进行认证。在 Karakeep 设置中生成 API Key 后按如下方式初始化import { createKarakeepClient } from karakeep/sdk; // Create a client const apiKey my-super-secret-key; const addr https://karakeep.mydomain.com; const client createKarakeepClient({ baseUrl: ${addr}/api/v1/, headers: { Content-Type: application/json, authorization: Bearer ${apiKey}, }, });参数说明baseUrl指向 Karakeep 服务器的 REST API 根路径固定为https://你的域名/api/v1/。注意末尾的斜杠SDK 会在此基础路径上拼接端点路径。headers.authorization必须携带Bearer apiKey前缀。服务端通过 packages/api/middlewares/auth.ts 校验 token未认证请求会返回401 Unauthorized。Content-Type声明请求体为 JSON。此外SDK 还导出类型KarakeepAPISchemas即components[schemas]可以用于标注你自己的业务类型例如import type { KarakeepAPISchemas } from karakeep/sdk; type Bookmark KarakeepAPISchemas[Bookmark];四、核心操作创建与搜索书签初始化客户端后最典型的两个操作是创建书签与搜索书签这也是 README 中的官方示例。4.1 创建一条书签// Create a bookmark const { data: createdBookmark, response: createResponse, error: createError, } await client.POST(/bookmarks, { body: { type: text, title: Search Test 1, text: This is a test bookmark for search, }, }); console.log(createResponse.status, createdBookmark, createError);从生成的 API 类型karakeep-api.d.ts看POST /bookmarks支持三种书签类型body.type决定内容结构类型必填字段说明linkurl链接书签若 URL 已存在会返回既有书签HTTP 200 而非 201texttext文本/笔记书签可选sourceUrlassetassetType、assetId图片或 PDF 书签需先通过上传接口获得assetId公共可选字段还包括title、note、summary、archived、favourited、createdAt、crawlPrioritylow/normal、sourceapi/web/cli/mobile/extension/singlefile/rss/import等。返回值是三元组data成功时的响应体类型为Bookmark、response原始 Response可用response.status判断 200/201、error失败时的错误信息通常为带code与message的ErrorSchema。4.2 搜索书签// Search for bookmarks const { data: searchResults, response: searchResponse, error: searchError, } await client.GET(/bookmarks/search, { params: { query: { q: test bookmark, }, }, }); console.log(searchResponse.status, searchResults, searchError);GET /bookmarks/search的q参数支持全文搜索覆盖标题、正文、描述与笔记按相关性排序Karakeep 的语义搜索与混合排序模式则仅支持相关性排序详见 karakeep-api.d.ts 中的端点描述。搜索语法本身可参考仓库文档 search-query-language.md。五、进阶能力分页、读取与标签管理SDK 的类型定义覆盖了 API 的全量能力这里列举几个高频场景5.1 分页列出书签GET /bookmarks返回PaginatedBookmarks包含bookmarks数组与nextCursor为null表示没有下一页。查询参数支持archived、favourited过滤、sortOrderasc/desc、limit与cursor游标分页includeContent设为false可让响应更轻量仅元数据见 karakeep-api.d.ts。const page1 await client.GET(/bookmarks, { params: { query: { limit: 50, sortOrder: desc } }, }); if (page1.data?.nextCursor) { const page2 await client.GET(/bookmarks, { params: { query: { cursor: page1.data.nextCursor, limit: 50 } }, }); }5.2 读取可读化内容GET /bookmarks/{bookmarkId}/content返回分块chunked的 agent 可读内容content、range起始/结束偏移与总字符数、truncated标志以及用于续读的nextCursor。链接书签内容来自提取的 HTML文本与媒体书签则使用存储或提取的文本。对大书签可循环携带nextCursor完整拉取。5.3 附加与移除标签POST /bookmarks/{bookmarkId}/tags附加标签、DELETE /bookmarks/{bookmarkId}/tags移除标签标签既可用id也可用name标识——按名称传入且标签不存在时会自动创建见 karakeep-api.d.ts。书签响应中的tags数组还带有attachedBy字段ai/human用于区分 AI 自动标签与人工标签。六、认证与权限API Key 的作用域模型SDK 示例使用的是 API KeyBearer Token其权限由服务端的作用域scope机制控制。从 packages/api/middlewares/apiKeyScopes.ts 的源码可以看到服务端中间件会校验请求资源ZApiKeyScopeResource与操作ZApiKeyScopeAccess是否被 API Key 的作用域覆盖不满足则返回403错误信息形如API key is missing required scope: scope。这意味着API Key 的权限是细粒度的如果某个端点调用返回 403请先检查该 Key 在 Karakeep 设置中是否被授予了相应资源/操作的 scope而不是简单地认为 Key 无效。认证失败401与权限不足403在 SDK 的error返回中会以不同状态呈现建议在业务代码中分别处理。七、API 文档与版本策略7.1 API 文档SDK 的类型定义即 API 契约。仓库的 OpenAPI 规范与文档位于 packages/open-api/karakeep-openapi-spec.jsondocs/docs/api 目录下还有按端点组织的 API 参考如 create-bookmark.api.mdx、search-bookmarks.api.mdx、list-bookmarks.api.mdx 等包含完整的请求/响应示例可与 SDK 类型对照阅读。7.2 版本策略README 明确了两条版本约定这也是使用 SDK 时最容易踩坑的地方SDK 版本跟随服务器次版本Karakeep 服务器0.21.0引入的新 API会从 SDK 的0.21.0版本起可用。因此升级服务器时也应同步升级 SDK 到相同或更高次版本以免缺少新端点类型。向后兼容承诺Karakeep 尽力保持 API 向后兼容因此较旧版本的 SDK 通常仍可配合新版服务器使用旧版本可能缺少新增端点但既有端点的调用不会破坏。当前仓库中 SDK 版本为0.33.0与 packages/db 等模块的服务端版本体系保持一致。八、总结何时使用 SDKkarakeep/sdk适合以下场景编写脚本或工具批量导入/导出书签、标签、列表与高亮在 Node.js 服务中集成 Karakeep例如将收藏数据同步到内部系统构建自定义客户端、CLI 或 Agent 工作流——SDK 暴露的createKarakeepClient让 REST 调用获得完整类型提示几乎不可能拼错路径或请求体字段。如果你的场景需要更粗粒度的能力可以关注仓库中的 packages/cli命令行工具与 apps/mcpMCP 服务器它们同样基于这套 API而 SDK 则是把 API 直接嵌入你自己代码的最轻量方式。所有端点的完整类型定义都可以在 src/karakeep-api.d.ts 中查阅。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Karakeep SDK 使用指南：用 TypeScript 客户端操作自托管书签 API
Karakeep SDK 使用指南用 TypeScript 客户端操作自托管书签 API【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder导读Karakeep原 Hoarder是一款自托管收藏一切应用支持链接、笔记和图片并提供基于 AI 的自动标签与全文搜索。karakeep/sdk是官方 TypeScript SDK基于openapi-fetch与自动生成的 OpenAPI 类型封装 REST 接口让你在几行代码内完成书签创建、检索、搜索、列表与标签管理等操作。读完本文你将掌握 SDK 的安装方式、客户端初始化、典型增删改查与搜索调用以及其版本策略与类型安全背后的实现原理。一、SDK 是什么从源码看它的真实构成karakeep/sdk包位于 packages/sdk其核心入口 src/index.ts 只有短短十几行却揭示了这个 SDK 的设计哲学——它不是一个臃肿的封装层而是直接建立在openapi-fetch之上的薄封装import createClient from openapi-fetch; import type { components, paths } from ./karakeep-api.d.ts; // deprecated Use createKarakeepClient instead. export const createHoarderClient createClientpaths; export const createKarakeepClient createClientpaths; export type KarakeepAPISchemas components[schemas];关键点解读两个客户端工厂createKarakeepClient是推荐入口createHoarderClient是历史遗留的旧名源码中以deprecated标注仅用于向后兼容。类型即文档paths与components来自 src/karakeep-api.d.ts该文件由openapi-typescript从服务端 OpenAPI 规范自动生成文件头注释明确标注 This file was auto-generated by openapi-typescript定义了全部端点路径、请求参数与响应 Schema。零手写请求逻辑所有 HTTP 调用行为fetch、请求/响应类型校验、错误处理全部由openapi-fetch提供SDK 本身只负责接入类型。构建配置方面vite.config.mts 将 SDK 打包为es与cjs双格式index.mjs/index.js并生成类型声明vite-plugin-dts同时把openapi-fetch声明为 external 依赖避免重复打包。这也解释了为什么 SDK 的运行时依赖只有openapi-fetch一个见 package.json。二、安装SDK 以 npm 包形式发布使用任意包管理器安装即可npm install karakeep/sdk提示从 package.json 可以看到main指向./src/index.tsworkspace 内直接使用源码发布时则通过publishConfig指向构建产物./dist/index.js、./dist/index.mjs与./dist/index.d.ts因此安装后同时支持 ESM 与 CommonJS 项目。当前仓库中该包的版本为0.33.0与 Karakeep 服务器次版本号一致详见后文版本策略。三、快速上手创建客户端SDK 使用 Bearer TokenAPI Key进行认证。在 Karakeep 设置中生成 API Key 后按如下方式初始化import { createKarakeepClient } from karakeep/sdk; // Create a client const apiKey my-super-secret-key; const addr https://karakeep.mydomain.com; const client createKarakeepClient({ baseUrl: ${addr}/api/v1/, headers: { Content-Type: application/json, authorization: Bearer ${apiKey}, }, });参数说明baseUrl指向 Karakeep 服务器的 REST API 根路径固定为https://你的域名/api/v1/。注意末尾的斜杠SDK 会在此基础路径上拼接端点路径。headers.authorization必须携带Bearer apiKey前缀。服务端通过 packages/api/middlewares/auth.ts 校验 token未认证请求会返回401 Unauthorized。Content-Type声明请求体为 JSON。此外SDK 还导出类型KarakeepAPISchemas即components[schemas]可以用于标注你自己的业务类型例如import type { KarakeepAPISchemas } from karakeep/sdk; type Bookmark KarakeepAPISchemas[Bookmark];四、核心操作创建与搜索书签初始化客户端后最典型的两个操作是创建书签与搜索书签这也是 README 中的官方示例。4.1 创建一条书签// Create a bookmark const { data: createdBookmark, response: createResponse, error: createError, } await client.POST(/bookmarks, { body: { type: text, title: Search Test 1, text: This is a test bookmark for search, }, }); console.log(createResponse.status, createdBookmark, createError);从生成的 API 类型karakeep-api.d.ts看POST /bookmarks支持三种书签类型body.type决定内容结构类型必填字段说明linkurl链接书签若 URL 已存在会返回既有书签HTTP 200 而非 201texttext文本/笔记书签可选sourceUrlassetassetType、assetId图片或 PDF 书签需先通过上传接口获得assetId公共可选字段还包括title、note、summary、archived、favourited、createdAt、crawlPrioritylow/normal、sourceapi/web/cli/mobile/extension/singlefile/rss/import等。返回值是三元组data成功时的响应体类型为Bookmark、response原始 Response可用response.status判断 200/201、error失败时的错误信息通常为带code与message的ErrorSchema。4.2 搜索书签// Search for bookmarks const { data: searchResults, response: searchResponse, error: searchError, } await client.GET(/bookmarks/search, { params: { query: { q: test bookmark, }, }, }); console.log(searchResponse.status, searchResults, searchError);GET /bookmarks/search的q参数支持全文搜索覆盖标题、正文、描述与笔记按相关性排序Karakeep 的语义搜索与混合排序模式则仅支持相关性排序详见 karakeep-api.d.ts 中的端点描述。搜索语法本身可参考仓库文档 search-query-language.md。五、进阶能力分页、读取与标签管理SDK 的类型定义覆盖了 API 的全量能力这里列举几个高频场景5.1 分页列出书签GET /bookmarks返回PaginatedBookmarks包含bookmarks数组与nextCursor为null表示没有下一页。查询参数支持archived、favourited过滤、sortOrderasc/desc、limit与cursor游标分页includeContent设为false可让响应更轻量仅元数据见 karakeep-api.d.ts。const page1 await client.GET(/bookmarks, { params: { query: { limit: 50, sortOrder: desc } }, }); if (page1.data?.nextCursor) { const page2 await client.GET(/bookmarks, { params: { query: { cursor: page1.data.nextCursor, limit: 50 } }, }); }5.2 读取可读化内容GET /bookmarks/{bookmarkId}/content返回分块chunked的 agent 可读内容content、range起始/结束偏移与总字符数、truncated标志以及用于续读的nextCursor。链接书签内容来自提取的 HTML文本与媒体书签则使用存储或提取的文本。对大书签可循环携带nextCursor完整拉取。5.3 附加与移除标签POST /bookmarks/{bookmarkId}/tags附加标签、DELETE /bookmarks/{bookmarkId}/tags移除标签标签既可用id也可用name标识——按名称传入且标签不存在时会自动创建见 karakeep-api.d.ts。书签响应中的tags数组还带有attachedBy字段ai/human用于区分 AI 自动标签与人工标签。六、认证与权限API Key 的作用域模型SDK 示例使用的是 API KeyBearer Token其权限由服务端的作用域scope机制控制。从 packages/api/middlewares/apiKeyScopes.ts 的源码可以看到服务端中间件会校验请求资源ZApiKeyScopeResource与操作ZApiKeyScopeAccess是否被 API Key 的作用域覆盖不满足则返回403错误信息形如API key is missing required scope: scope。这意味着API Key 的权限是细粒度的如果某个端点调用返回 403请先检查该 Key 在 Karakeep 设置中是否被授予了相应资源/操作的 scope而不是简单地认为 Key 无效。认证失败401与权限不足403在 SDK 的error返回中会以不同状态呈现建议在业务代码中分别处理。七、API 文档与版本策略7.1 API 文档SDK 的类型定义即 API 契约。仓库的 OpenAPI 规范与文档位于 packages/open-api/karakeep-openapi-spec.jsondocs/docs/api 目录下还有按端点组织的 API 参考如 create-bookmark.api.mdx、search-bookmarks.api.mdx、list-bookmarks.api.mdx 等包含完整的请求/响应示例可与 SDK 类型对照阅读。7.2 版本策略README 明确了两条版本约定这也是使用 SDK 时最容易踩坑的地方SDK 版本跟随服务器次版本Karakeep 服务器0.21.0引入的新 API会从 SDK 的0.21.0版本起可用。因此升级服务器时也应同步升级 SDK 到相同或更高次版本以免缺少新端点类型。向后兼容承诺Karakeep 尽力保持 API 向后兼容因此较旧版本的 SDK 通常仍可配合新版服务器使用旧版本可能缺少新增端点但既有端点的调用不会破坏。当前仓库中 SDK 版本为0.33.0与 packages/db 等模块的服务端版本体系保持一致。八、总结何时使用 SDKkarakeep/sdk适合以下场景编写脚本或工具批量导入/导出书签、标签、列表与高亮在 Node.js 服务中集成 Karakeep例如将收藏数据同步到内部系统构建自定义客户端、CLI 或 Agent 工作流——SDK 暴露的createKarakeepClient让 REST 调用获得完整类型提示几乎不可能拼错路径或请求体字段。如果你的场景需要更粗粒度的能力可以关注仓库中的 packages/cli命令行工具与 apps/mcpMCP 服务器它们同样基于这套 API而 SDK 则是把 API 直接嵌入你自己代码的最轻量方式。所有端点的完整类型定义都可以在 src/karakeep-api.d.ts 中查阅。【免费下载链接】hoarderA self-hostable bookmark-everything app (links, notes and images) with AI-based automatic tagging and full text search项目地址: https://gitcode.com/GitHub_Trending/ho/hoarder创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
)
