Kanera API

Kanera 的公共 API 允许您围绕团队在应用中管理的相同工作构建集成:工作区、看板、卡片、列表、看板分隔符、评论、清单、笔记、附件、标签、自定义字段、任务、排名最高的下一行队列、活动和外部链接。

当 Kanera 需要连接到另一个系统、支持内部工作流程、迁移数据、构建报告或让其他工具创建和更新 Kanera 工作时,请使用 API。

您可以构建什么

常见的 API 用例包括:

将 Kanera 卡片与其他工作跟踪工具同步。
从表单、支持票据、聊天消息或 CRM 记录创建卡片。
从看板、作业、标签、自定义字段和活动构建自定义报告仪表板。
从另一个系统导入工作到 Kanera。
保持外部记录链接到Kanera卡或笔记.
从其他工具添加评论或状态更新。
上传并附加文件到卡片或笔记。
读取活动历史记录以进行审计、报告或自动化。

Kanera 集成可以针对独立的看板或工作区,独立的看板具有自己的列表、标签和自定义字段。工作区在其看板之间共享这些资源,这样可以更轻松地保持跨看板报告和同步工作流的一致性。

官方客户

你不必从 curl。两个第一方客户端包装相同的 API：

客户	安装	用于
Kanera CLI	`npm install --global @kanera/cli`	终端使用、shell 脚本和可以运行命令的 AI 代理。
TypeScript SDK	`npm install @kanera/sdk`	TypeScript 和 JavaScript 集成。无运行时依赖关系;可在 Node、Bun、Deno、Workers 和浏览器上运行。

SDK 是 MIT 许可的,因此将其嵌入到您自己的应用程序中不会引起许可政策问题。直接使用 REST 端点来处理任何其他语言。

API参考

Kanera REST API 位于:

https://api.kanera.app

详细的终端级参考资料可在以下网站查阅：

https://api.kanera.app/docs

公共 API 服务包括端点级别参考:

路径	使用
`/docs`	交互式标量 API 参考。
`/swagger`	Swagger UI 参考。
`/openapi.json`	用于 SDK 生成和工具的 OpenAPI 文档。

对于Kanera,打开:

https://api.kanera.app/docs
https://api.kanera.app/swagger
https://api.kanera.app/openapi.json

使用此页作为入门指南,然后使用 API 参考来了解确切的端点路径、请求正文、响应架构和可用的 webhook 事件类型。

使用端点引用

开放标量每个操作都显示其方法和路径、所需作用域、路径和查询参数、请求架构、响应架构和错误响应。使用授权当你想尝试一个请求时,提供一个载体令牌。

使用斯瓦格尔当您的工具或工作流程围绕 Swagger 构建时。下载 JSON 用于 SDK 生成、请求验证或将 API 导入到另一个客户端。

从参考文档中复制一个示例,而不是猜测请求正文,并在自动化之前对照预期工作区测试写入或删除操作。

终点群

集团	典型的操作
工作区和看板	发现无障碍作品,打开完整的看板状态,管理成员和访客,并创建或重新排列看板。
列表、分隔符和卡片	创建、更新、定位、移动、完成、存档、复制和批量编辑工作。
说明和附录	创建嵌套笔记、管理锁和反向链接、直接上传文件或通过一次性上传链接上传文件,以及读取附件字节。
便笺	阅读呼叫者的私人 Scratchpad 页面,并将快速任务捕获到收件箱页面。
字段和标签	管理工作区级别的自定义字段、选项和可重复使用的卡片标签。
评论和活动	阅读卡片源,写评论和反应,并审查板活动。
下一个优先事项	发现可读队列、列出队伍顺序,并添加、移动或删除排名卡。
下列	观看或停止观看卡片和看板,设置、清除或列出您的私人卡片提醒,并查询您的通知收件箱。
代理运行	宣布代理正在处理一张卡，在其运行时发出心跳，并记录其结束方式。
搜索和外部链接	搜索无障碍内容并维护与其他系统中的记录的等效映射。
Webhook	注册和管理端点,检查或重试交付,并在不进行调查的情况下接收已签名的更改事件。

选择 API 密钥类型

Kanera 有两种 API 密钥类型,它们的身份验证方式相同,但访问模式不同。

密钥类型	从中创建它	使用它时	接入模式
个人 API 密钥	配置文件设置 -> API 密钥	您正在连接自己的脚本、CLI 或 MCP 客户端,并希望它能够跨您可以个人访问的主板工作。	在您可以访问的每个工作区和看板中以您的身份行事，尊重您在每个看板中的角色。其阅读或写作用域限制了它在该访问权限范围内可以执行的操作。
工作区或板 API 密钥	工作区设置 -> API 或主板设置 -> API	您正在为一个工作区或独立的看板设置团队集成、服务帐户、webhook 生成器、同步作业或自动化。	适用于该工作区或独立板。阅读, 写, 或管理员范围控制了集成可以做什么。

对于应与目标共享、轮换和审核的共享或生产集成,请使用范围工作区或看板密钥。

计划所需资源

个人 API 密钥和交互式 AI 代理连接 每个计划，包括托管的 Free。他们充当当前用户，因此他们准确地到达用户可以打开的面板，在 Free 和 Pro 组织中都是如此。

工作区和看板 API 密钥、无人值守 OAuth 服务代理、webhook 和聊天目标需要 Pro 30天 Pro试用。它们代表组织运行，无需任何人登录，因此它们在托管 Free 上不可用，其中工作区设置页面对此进行了解释，而不是显示创建表单。因计划限制返回而阻止的请求 403 错误代码: PLAN_LIMIT，因此集成可以区分计划问题和权限问题。

创建工作区或论坛 API 密钥、OAuth 客户端和聊天目标需要 工作区管理员 管理员还可以管理工作区中的每个 Webhook 端点;当其用户是工作区成员时,具有写入功能的 API 凭据或交互式 OAuth 代理可以注册范围为其自身连接的端点。无需创建工作区角色即可创建个人 API 密钥。

当一个托管组织迁移到一个新的服务器时,它的服务器名称会被更改。 Free, Kanera 撤销其活动工作区和看板 API 还有,这也是一个很好的例子。 OAuth 服务代理建立在他们之上,并且 /api/v1 个人 API 密钥和交互式代理连接仍然可以使用。 Webhook 端点和聊天目标将由同一降级暂停。升级回 Pro 版本将恢复降级时触及的密钥和端点。

费率限额

通过 REST 和 MCP 发出的 API 密钥和 AI 代理请求,按照拥有所访问看板的组织的计划限制,对每个用户都有限制:

看板的组织	每秒	每分钟
主办 Free	5	60
托管 Pro 或 Pro 试用版	20	400
自我托管	20	400（可配置）

同时属于 Free 和 Pro 组织的用户将获得每个组织对其自己的面板的限制。超过限制的请求不会立即被拒绝：最多 10 个请求在队列中等待，最多 10 秒，并作为容量释放来提供。仅接收超出该队列的请求 429 与 Retry-After CLI、SDK 和 MCP 服务器将自动退出并重试。

自托管运营商可以通过 PUBLIC_API_KEY_RATE_LIMIT_PER_SECOND, PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE, PUBLIC_API_RATE_LIMIT_QUEUE_SIZE, 和 PUBLIC_API_RATE_LIMIT_QUEUE_MAX_WAIT_MS。参见 Webhook 对于完全降级行为。

创建个人 API 密钥

开放 配置文件设置.
去看看 API 键 选项卡
创建个人 API 密钥。
选择只读或 阅读和写作.
添加可选的私有标签，以便您可以识别密钥的使用位置。
当它显示时,复制密码。

私钥总是与创建它的用户绑定,它们跟随所有者的真实论坛访问权限和角色,并且活动显示为所有者。没有管理员范围:无论其所有者的角色如何,私钥都不能执行工作区管理。

只读私钥

个人密钥是读写除非你另外选择,这是现有键或未更改的创建流给你的。

选择只读当凭据被发送到某个你不会关注的地方时:一个AI代理,一个报告作业,一个CI检查,一个仪表板。只读密钥可以列出,读取,搜索和报告,而Kanera拒绝每一个与 403 错误代码: FORBIDDEN。由于拒绝发生在 API 而不是客户端，因此行为不当或提示注入的代理仍然无法更改您的工作。

创建密钥时,作用域是固定的,要更改它,请创建新密钥并撤销旧密钥。

秘密显示一次,并存储在本地秘密管理器、MCP 客户端配置或环境变量中。

创建工作区或论坛 API 密钥

打开工作区或独立看板。
去看看 工作区设置 -> API 或 主板设置 -> API.
创建工作区 API 密钥。
选择适合集成的最小范围。
当它显示时,复制密码。

工作区 API 密钥的作用域限定为工作区。密钥只能访问其创建时所在工作区的资源，而且创建者必须仍然拥有相应访问权限。

秘密显示一次,并存储在集成的秘密管理器或环境变量中。

Workspace API 关键作用域

范围	使用它时
阅读	集成只需要读取、搜索、报告或导出 Kanera 数据。
写	集成需要创建或更新工作,例如卡片、注释、标签、分配人、自定义字段值、备注或附件。
管理员	集成需要管理员级公共 API 操作(如受支持 ) 。

阅读, 写, 和 管理员 个人密钥可以在两种类型之间选择: 阅读以及写只能继承所有者的板级权限,并且总是继承所有者的板级权限。

对于单独的集成,使用单独的 API 密钥,这样可以更轻松地撤销、轮换和审核访问权限。对于共享系统,最好使用工作区密钥,以便访问权限不会与某个人的个人工具挂钩。

认证

将 API 密钥作为载体令牌发送:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer kanera_live_..."

Kanera API 密钥使用环境前缀:

前缀	环境
`kanera_live_...`	生产
`kanera_stg_...`	阶段化
`kanera_dev_...`	发展
`kanera_test_...`	测试

个人钥匙携带一个 u 供应商前缀后的标记,所以 kanera_u_live_... 是私钥和 kanera_live_... 是工作区或看板密钥,两者的身份验证方式相同。

丢失或无效的密钥返回 401。未经资源或操作返回许可的有效密钥 403 包括使用读取范围密钥进行的写入尝试。

面向 AI 代理的 OAuth

Kanera 支持 OAuth 2.0,因此兼容的 AI 代理可以通过浏览器同意或服务连接连接到 Kanera MCP,而无需存储 API 密钥。

OAuth 连接用于 MCP；它不是一般公共 API 凭证。当您自己的集成需要调用时，使用个人、工作区或板 API 密钥 /api/v1 直接。

有三种 OAuth 路径:

交互代理 使用 PKCE 的授权代码流程。一个人在浏览器中批准连接一次,代理将以该用户的身份行事。这是兼容的 MCP 客户端(如 Claude、ChatGPT、Copilot 和 Codex)在不使用 API 密钥的情况下连接的方式。
设备客户端 使用设备授权授权 (urn:ietf:params:oauth:grant-type:device_code）。客户端显示一个简短的代码，一个人在任何设备上的浏览器中批准它，然后客户端轮询令牌。将此用于无法接收浏览器重定向的 CLI 或无头客户端。请参阅设备授权参考.
无人值守代理 使用 client_credentials 您可以在客户端中创建一个客户端ID和一个秘密。 工作区设置 -> API 并将其交换为短期令牌,无需浏览器步骤。用于 CI、cron 或服务器端代理。

海连接 AI 代理用于设置、作用域和连接管理。定制 OAuth 客户端作者可以在协议详细信息中找到 MCP 技术参考.

Base URL and versioning

REST 端点的实时状态 /api/v1 关于公共 API 服务。

例如：

https://api.kanera.app/api/v1/workspaces

操作帮助路径,如 /docs, /swagger, /openapi.json、签名媒体 URL 和 Webhook 事件发现可能存在于外部 /api/v1 将 API 返回的已签名媒体 URL 视为不透明 URL,并按照提供的方式使用它们。

第一次请求

检查凭证充当谁的角色。 GET /api/v1/session 返回用户、组织、凭据类型,以及 scope (read 意味着每个更改都被拒绝 ), 加上用户的 timeZone 以及 today，该区域中的当前日期，因此客户端可以按照 Kanera 标记到期日期的方式解析“今天”或“明天”：

curl "$KANERA_PUBLIC_API_URL/api/v1/session" \
  -H "Authorization: Bearer $KANERA_API_KEY"

列出 API 密钥可以访问的工作区:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $KANERA_API_KEY"

然后列出工作区中的看板:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces/$WORKSPACE_ID/boards" \
  -H "Authorization: Bearer $KANERA_API_KEY"

打开一个看板以获取渲染或同步工作所需的看板、工作区列表、看板分隔符、可见卡片、成员、标签和自定义字段:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/open" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY"

创建卡片:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/cards" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Follow up with Acme"}'

创建也可以设置 labelIds, assigneeIds, dueDateLocalDate (YYYY-MM-DD），以及 dueDateSlot 相同的写入,因此卡片到达时已完全描述,其标签自动化运行一次。

一次创建多张卡片,每个请求最多50张。每张卡片都有自己的名字,并按照请求顺序放在底部:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/cards/bulk/create" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"cards\":[{\"listId\":\"$LIST_ID\",\"title\":\"Draft the brief\",\"labelIds\":[\"$LABEL_ID\"]},{\"listId\":\"$LIST_ID\",\"title\":\"Review with legal\",\"assigneeIds\":[\"$USER_ID\"],\"dueDateLocalDate\":\"2026-11-02\"}]}"

每张卡片在创建之前都会被检查,因此未知的列表、标签或受让人会以一个 400 给条目命名的字符串,例如 cards[1]: one or more label ids are invalid。然后，每张卡都会触发与单个创建相同的自动化、通知和 Webhook。

卡片响应包括不可变的 workspaceId, 不透明 organisationKey, 正 number，当前人类可读的 key 如 PROJ-123，并清洁浏览器 url。工作区前缀可能会更改，但卡号不会更改。

在调用基于 id 的变异端点之前解析当前或历史卡密钥:

curl "$KANERA_PUBLIC_API_URL/api/v1/organisations/$ORGANISATION_KEY/cards/by-key/$CARD_KEY" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Resolution 不区分大小写,并返回卡片的当前 id、工作区、板、列表、数字、键和浏览器 URL。组织键是 Kanera 返回的不透明值,而不是组织名称或 slug。 404.

更新卡片:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Imported from CRM"}'

添加评论：

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/comments" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Customer confirmed the rollout window."}'

用精确的集合替换卡片的标签或分配者:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/labels" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"labelIds\":[\"$LABEL_ID\"]}"

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/assignees" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"userIds\":[\"$USER_ID\"]}"

这两个 PUT 发送一个空数组来清除它;当你需要在选定的卡片上修补语义时,使用文档中记录的批量添加/删除操作。

完成一张卡片:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/completion" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

管理板分隔器

分隔符是工作流列表的混合卡片和分隔符排序通道中由板拥有、有标题、可选颜色的项目。在精确键入的锚点处创建一个：

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/separators" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"This week\",\"color\":\"blue\",\"beforeItem\":{\"type\":\"card\",\"id\":\"$CARD_ID\"}}"

更新其标题或颜色 PATCH /api/v1/separators/{id}, 移动它 POST /api/v1/separators/{id}/move，然后删除它 DELETE /api/v1/separators/{id}。移动实体命名目的地 listId 并且提供正好一个 beforeItem 或 afterItem;该项目可以是 { "type": "card", "id": "..." } 或 { "type": "separator", "id": "..." } 参考文献A null afterItem 上面的图片是什么意思? null beforeItem 删除分隔符会使卡片保持不变。

管理下一个订单

API 会公开 Home、My Cards 和 Team Cards 使用的相同排序队列:

终点	使用
`GET /api/v1/work/priority-targets`	列出凭据可以读取其队列的用户。
`GET /api/v1/work/priorities`	在一个响应中读取每个允许的队列。
`GET /api/v1/work/priorities/{userId}`	按排序读取一个队列。
`POST /api/v1/work/priorities/{userId}/cards`	在锚定位置添加指定的活动卡。
`POST /api/v1/card-priorities/{id}/move`	在另一个可见条目之前或之后移动一个队列条目。
`DELETE /api/v1/card-priorities/{id}`	删除条目而不更改卡片。

个人凭据始终可以读取自己的队列。读取另一个人的队列需要在共享工作区中拥有有效的管理员权限,写入也需要具有写入功能的凭据以及对目标卡的权限。使用队列返回的条目 ID 作为移动锚点;排名是显示值,而不是变异 ID。

附加和读取文件

POST /api/v1/cards/{id}/attachments 当文件位于调用者无法直接从中流式传输的位置时,例如 AI 代理的沙盒,则使用一次性上传链接,并且 PUT 对它的原始字节:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/MKT-42/attachments/upload-links" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"test-run.log"}'

# The response includes uploadUrl; no Authorization header is needed for the upload itself.
curl -fsS -T ./test-run.log "$UPLOAD_URL"

链接只能使用一次,15 分钟后过期,如果创建链接的密钥被撤销,则链接将停止工作。
Kanera 将文件存储在创建链接时记录的名称和类型下,当您省略时从扩展名推断类型 mimeType。日志文件（.log, .out, .jsonl，和类似的）存储为纯文本。
创建链接需要具有写入功能的凭据和编辑器对卡的访问权限。创建链接和文件到达时都会检查存储限制。
上传响应是新附件,任何查看卡片的人都会立即看到它。

用以下命令读取附件的字节 GET /api/v1/cards/{id}/attachments/{attachmentId}/content。它支持 Range 请求，以及 ?variant=cover （最大 1200 像素）或 ?variant=thumbnail (400px) 返回 Kanera 由 PNG、JPEG、GIF 和 WebP 图像组成的 JPEG 副本。

捕获到便签本

POST /api/v1/scratchpad/capture 将一个打开的任务附加到调用者的私人便笺，在第一页标题为 pageTitle （默认 Inbox)，并在页面丢失时创建该页面：

curl "$KANERA_PUBLIC_API_URL/api/v1/scratchpad/capture" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Renew the venue insurance"}'

GET /api/v1/scratchpad/notes 列出每个页面及其内容,并 PATCH /api/v1/scratchpad/notes/{id} 请输入一个页面名称。 updatedAt 你读作 baseUpdatedAt 待收款 409 SCRATCHPAD_STALE Scratchpad 属于一个人,因此工作区 API 密钥会收到一个用户的密钥。 403;使用个人密钥或 OAuth 连接。

查看卡片并设置提醒事项

该下列端点管理调用者自己的订阅,因此工作区 API 密钥接收 403;使用个人密钥或 OAuth 连接。更改它们需要可写入的凭据，但只能读取卡的权限。

终点	使用
`GET /api/v1/cards/{id}/follow`	是否看卡,和你的提醒它。
`PUT` / `DELETE /api/v1/cards/{id}/watch`	返回与返回相同的状态的函数。 `follow`.
`PUT` / `DELETE /api/v1/boards/{id}/watch`	观看或停止观看板。
`PUT /api/v1/cards/{id}/reminder`	设置您的提醒: `{"remindAt": "2026-10-16T15:00:00+01:00"}`.
`DELETE /api/v1/cards/{id}/reminder`	清除你的提醒。
`GET /api/v1/reminders`	您的待处理提醒,最早的第一。 `?status=all` 包括那些已经发射的。
`GET /api/v1/notifications`	从光标向前调查您的通知收件箱。见下文。

remindAt 是一种带有偏移的 ISO 快照,位于未来并且最多提前 56 天(8 周 ) 。每张卡片都有一个提醒,因此重新设置它会替换并重新武装它。您的其他打开的会话将立即更新。提醒事项.

GET /api/v1/notifications 是指不能接收 webhook 的脚本或代理,例如在笔记本电脑上运行的脚本或代理。它返回的行与通知抽屉式导航栏中的行相同(回复、提及、分配以及您关注或分配的卡片上的更改 ), 从最旧的开始。 since 然后再把它们传递给我们。 cursor 返回 since, 重复同时 hasMore 是 true，只获取新内容。每行有一行 summary, 的 card 关键字和URL, actor，和一个 commentExcerpt 事件发生后几秒钟会显示行。 AI 代理连接不会看到由其自身写入引起的通知,除非您添加了 includeSelf=true，并且轮询从不标记任何已读内容。

跟踪座席的流动工作

当调用者是 AI 代理而不是同步作业时,它可以宣布它正在卡片上进行的工作。 Kanera 然后在卡片瓷砖上显示实时芯片,在卡片详细信息中列出运行情况,并记录开始和结束的卡片活动行 — 这样,人们可以看到正在发生的事情以及谁在做这件事,而无需等待结果。

终点	使用
`POST /api/v1/cards/{cardId}/agent-runs`	开始跑步。身体需要 `title` （必填）， `summary`, 和 `externalUrl`.
`GET /api/v1/cards/{cardId}/agent-runs`	默认情况下仅显示实时数据;通过 `includeEnded=true` 历史,最新的第一。
`GET /api/v1/agent-runs/{id}`	读一遍。
`PATCH /api/v1/agent-runs/{id}`	更新、心跳或完成运行。每个字段都是可选的,因此请在 `{}` 是一种裸体的心跳。

开始运行,并保持 id 从答复中:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/agent-runs" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Implementing OAuth refresh","externalUrl":"https://github.com/acme/api/pull/482"}'

然后报告进度并关闭它:

curl "$KANERA_PUBLIC_API_URL/api/v1/agent-runs/$RUN_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"succeeded","summary":"Merged in PR 482; realtime suite green."}'

状态是 running, blocked, succeeded, failed, cancelled, 和 stalled:

running 以及 blocked 两个实时状态。使用 blocked 当代理等待某人时,例如提问或批准;卡片的芯片变成琥珀色。
succeeded, failed, 和 cancelled 终端状态结束运行并使其不可变,因此任何后续的运行都会被终止。 PATCH 回返 409 与 message: agent run has already ended.
stalled 当一个实时运行停止心跳 15 分钟时,由 Kanera 设置,而不是由您设置,因此崩溃的代理不能无限期地留下显示"正在运行"的卡片。停滞运行不会结束:代理仍然可以通过终端状态关闭它,或者设置 running 恢复。

每 PATCH 刷新心跳,包括一个不改变任何东西的,所以在一个长的作业中,在十五分钟的窗口内发送一个 keep-alive 函数。编辑与任何其他卡一样,它也会发出一个信号,告诉您要如何访问和写入。 agentRun:started 以及 agentRun:updated webhook事件.

代理通过连接 OAuth 作为代理代替其用户的代理被记录:其运行、注释和 Activity 行包含代理的名称,并且代理人会收到代理所做操作的通知。您自己的脚本使用的个人 API 密钥仍然作为其所有者。

从集成注册 webhook

工作区管理员可以管理每个通用 Webhook 端点。非管理员写入 API 凭据或交互式 OAuth 代理也可以在其用户属于工作区时创建一个;Kanera 会标记该端点 scope: "connection"，并且只有相同的连接和工作区管理员才能列出或管理它。这使得代理可以订阅看板事件，而无需获得工作区管理员权限。

使用 POST /api/v1/workspaces/{workspaceId}/webhooks 创建终端点并保存一次性 secret 同一资源公开列表、更新、删除、秘密轮换、交付历史记录和交付失败重试操作。参见 Webhook 用于端点映射和签名规则。

可靠的集成流程

致电 GET /api/v1/workspaces 或 GET /api/v1/boards 仅发现凭据可以访问的资源。
使用 POST /api/v1/boards/{id}/open 当您需要在一个响应中显示板及其列表、卡片、成员、标签和自定义字段时。
存储返回的 API 突变 ID。名称可编辑;当人或外部记录提供一个人可读的卡片密钥时,可以解析为当前卡片 ID。
对照 Scalar 或 OpenAPI 中的操作模式验证写入主体。
特里特 401 作为无效的认证, 403 作为不足的进入或计划门, 404 作为丢失或无法访问的数据, 409 作为国家冲突,以及 429 作为一个信号,让他们退后。
记录响应 x-request-id 集成日志中,而不记录凭据或敏感内容。

卡牌关系

关系将卡片连接到同一工作区,包括其各个看板。 direction 从路径中的卡读取: blocks 意味着这张牌阻挡目标, blocked_by 意味着目标阻挡了这张牌,并且 relates_to 没有必要的顺序。

方法和途径	目的
`GET /api/v1/cards/{cardId}/relations`	读取可见关系和 `hiddenBlockerCount`.
`POST /api/v1/cards/{cardId}/relations`	添加 `{ "targetCardId": "<UUID>", "direction": "blocked_by" }`.
`DELETE /api/v1/cards/{cardId}/relations/{relationId}`	按照其 ID 删除关系。

卡详细信息包括 relations 以及 hiddenBlockerCount;卡片摘要暴露 blockedByCount。当至少一个先决条件不完整且未存档时，活动卡将被阻止。使用 filters: { blockedOnly: true } 与 POST /api/v1/work/cards/query 只返回被封闭的开放牌,或 atRiskOnly: true 对于其可见的阻止者已过期或在他们之后到期的开放卡。 POST /api/v1/work/portfolio/query 回返 blocked 以及 atRisk 计数每板和其总数。

添加现有关系是幂等的。自链接、跨工作区链接、依赖循环以及作为新阻止程序的完整卡片都会被拒绝。写入需要对路径卡和被阻止的卡进行编辑访问，以及对另一张卡进行读取访问。读取时忽略不可访问的关系；他们的主动阻断剂只有助于 hiddenBlockerCount.

清除最后一个活动的阻止器可以运行自动化并发送传递通知。重新打开或恢复阻止器可能会再次阻止卡片。通过 API 完成仍然可用,而不会出现 Web 应用的交互式警告。卡片关系与阻塞生命周期行为。

依赖图

POST /api/v1/cards/dependency-graph 读取 Dependencies 视图后面的图形。传递一个作用域:

{ "boardId": "<board UUID>" }

或者通过 { "workspaceId": "<workspace UUID>" } 或 { "cardIds": ["<card UUID>"] }。卡 ID 范围接受 1–2,000 个 UUID。这篇文章是没有副作用的阅读。

响应包含紧凑型卡片摘要、边缘、板/列表/标签/人物查找、卡片表面自定义字段以及 truncated。每张卡牌都会增加 inScope 及其标准 url。每块板包括 canEdit 调用者的依赖关系编辑权限。 A blocks 边缘运行从 sourceCardId （前提条件） targetCardId （受抚养人）； relates_to 是对称的。

步行从开放的、未归档的、有关系的范围卡开始,沿着可读的板的两个方向的封闭边缘,并停止在完成的卡上。相关邻居从种子中包括一个跳跃,不可访问的卡被省略; blockedByCount 图表停在400张牌,并设置了一个新的数字。 truncated: true;当需要完整的链条时缩小范围。工作区凭据保留在其工作区内。

海依赖关系 MCP 返回的是扩展的面向代理的投影,而不是这些紧凑的摘要。

看板和工作区模型

Kanera的API代表了两种面向用户的模型:

标准工作区包含多个板。
返回一个独立的板 kind: "board" 由暴露其支持容器的端点所组成,但用户将其视为一个独立的看板。
棋盘包含卡片。
列表、标签和自定义字段只属于独立看板,或者在标准工作区的每个看板中共享。
分配端点可以返回工作区中跨板分配的卡片。
私有板只能在 API 密钥具有访问权限的地方可见。
个人密钥可以查看其所有者有权访问的工作区中的看板。
工作区键只能看到其一个工作区内的板。

在工作区中,重复使用现有列表和字段,以便报告、分配查询和自定义字段聚合保持一致。全局工作 UI 可以跨越已登录人员可以访问的所有看板,而工作区 API 密钥的作用域仍保持在其一个工作区。

分页和错误

列出支持分页使用的端点:

参数	意义
`limit`	要返回的记录数。
`before`	时间戳前的记录的光标式过滤器。

错误返回 JSON 并包含:

外地	意义
`code`	稳定的错误代码。
`message`	人类可读错误消息。
`issues`	可选验证详细信息。

在决定是否重试、修复输入或要求管理员更新访问权限时,请同时使用 HTTP 状态代码和错误代码。

Webhook

Webhook 允许外部系统在 Kanera 中的工作变化时做出反应。参见 Webhook 设置、交付验证以及支持的 webhook 事件类型的完整列表。

如果目标是将卡片活动发布到团队聊天通道,则无需构建任何内容: 聊天通知目标适用于 Slack、Discord、Telegram 或 Zulip。

外部链接

外部链接允许集成存储 Kanera 记录与另一系统中的记录之间的持久映射。

例如,Trello 同步可以记住哪张Kanera卡片映射到哪张Trello卡片,而不需要在卡片描述中放置隐藏的集成元数据。

安全建议

每个集成使用一个 API 密钥。
使用最小的可行范围。
在秘密管理器中存储密钥和 webhook 秘密。
当人员离开或系统发生变化时,轮换密钥和 webhook 秘密。
请勿将 API 密钥放置在 Scratchpad、笔记、卡片、评论、源代码控制、日志或截图中。
在处理有效负载之前验证 webhook 签名。
使 webhook 处理程序具有同源性,因为交付可能会重试。
记录足够的请求和事件 ID,以便调试同步行为,而不记录秘密。

您可以构建什么​

官方客户​

API参考​

使用端点引用​

终点群​

选择 API 密钥类型​

计划所需资源​

费率限额​

创建个人 API 密钥​

只读私钥​

创建工作区或论坛 API 密钥​

Workspace API 关键作用域​

认证​

面向 AI 代理的 OAuth​

Base URL and versioning​

第一次请求​

管理板分隔器​

管理 下一个订单​

附加和读取文件​

捕获到便签本​

查看卡片并设置提醒事项​

跟踪座席的流动工作​

从集成注册 webhook​

可靠的集成流程​

卡牌关系​

依赖图​

看板和工作区模型​

分页和错误​

Webhook​

外部链接​

安全建议​

相关页面​