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​

外部連結​

安全建議​

相關頁面​