KaneraAPI

Kanera のパブリック API を使用すると、チームがアプリ内で管理するのと同じ作業 (ワークスペース、ボード、カード、リスト、ボード区切り文字、コメント、チェックリスト、メモ、添付ファイル、ラベル、カスタムフィールド、割り当て、次のランクアップキュー、アクティビティ、外部リンク) を中心とした統合を構築できます。

Kanera が別のシステムに接続する必要がある場合、内部ワークフローを強化する必要がある場合、データを移行する必要がある場合、レポートを作成する必要がある場合、または別のツールで Kanera を作成および更新できるようにする場合は、API を使用します。

構築できるもの

一般的な API の使用例は次のとおりです。

Kanera カードを別の作業トラッカーと同期します。
フォーム、サポートチケット、チャットメッセージ、または CRM レコードからカードを作成します。
ボード、割り当て、ラベル、カスタムフィールド、アクティビティからカスタムレポートダッシュボードを構築します。
別のシステムからKaneraに作業をインポートします。
外部記録をKaneraカードまたはメモにリンクして保管します。
別のツールからコメントやステータス更新を追加します。
ファイルをアップロードしてカードまたはメモに添付します。
監査、レポート、自動化のためにアクティビティ履歴を読み取ります。

Kanera 統合は、スタンドアロンのボードまたはワークスペースをターゲットにすることができます。スタンドアロンボードには、独自のリスト、ラベル、カスタムフィールドがあります。ワークスペースはこれらのリソースをボード全体で共有するため、ボード間のレポート作成と同期ワークフローの一貫性を維持しやすくなります。

オフィシャルクライアント

から始める必要はありません curl。 2 つのファーストパーティクライアントが同じ API をラップします。

クライアント	インストール	用途:
Kanera CLI	`npm install --global @kanera/cli`	ターミナルの使用、シェルスクリプト、およびコマンドを実行できる AI エージェント。
TypeScript SDK	`npm install @kanera/sdk`	TypeScript と JavaScript の統合。実行時の依存関係はありません。 Node、Bun、Deno、ワーカー、ブラウザ上で実行されます。

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 イベントタイプを確認してください。

エンドポイント参照を使用する

開くスカラー主要エンドポイント参照用。各操作には、そのメソッドとパス、必要なスコープ、パスとクエリパラメーター、要求スキーマ、応答スキーマ、およびエラー応答が表示されます。使用する 承認する リクエストを試す際にBearerトークンを指定します。

使用する Swagger UI ツールやワークフローがSwaggerを中心としている場合。次をダウンロードします： OpenAPI JSON SDK の生成、リクエストの検証、または別のクライアントへの API のインポート用。

OpenAPI ドキュメントは真実の情報源です。リクエスト本文を推測するのではなく、リファレンスから例をコピーし、自動化する前に目的のワークスペースに対して書き込み操作または削除操作をテストします。

エンドポイントグループ

グループ	代表的な操作
ワークスペースとボード	アクセス可能な作品を発見し、ボード全体の状態を開き、メンバーとゲストを管理し、ボードを作成または並べ替えます。
リスト、区切り文字、カード	作業を作成、更新、配置、移動、完了、アーカイブ、複製、および一括編集します。
注意事項と添付ファイル	ネストされたメモを作成し、ロックとバックリンクを管理し、ファイルを直接またはワンタイムアップロードリンク経由でアップロードし、添付ファイルのバイトを読み取ります。
スクラッチパッド	発信者のプライベートスクラッチパッドページを読み取り、簡単なタスクを受信トレイページにキャプチャします。個人の資格情報のみ。
フィールドとラベル	ワークスペースレベルのカスタムフィールド、オプション、再利用可能なカードラベルを管理します。
コメントとアクティビティ	カードフィードを読み、コメントや反応を書き、掲示板のアクティビティを確認します。
次の優先事項	読み取り可能なキューを検出し、チームの順序をリストし、ランク付けされたカードを追加、移動、または削除します。
フォロー中	カードやボードの監視や監視の停止、プライベートカードリマインダーの設定、消去、リストの作成、通知受信トレイのポーリングを行います。個人の資格情報のみ。
エージェントの実行	エージェントがカードを処理していることをアナウンスし、カードの実行中にハートビートを発生させ、終了方法を記録します。
検索と外部リンク	アクセス可能なコンテンツを検索し、他のシステムのレコードへのべき等マッピングを維持します。
Webhook	エンドポイントの登録と管理、配信の検査または再試行、ポーリングなしで署名された変更イベントの受信を行います。

API キーのタイプを選択してください

Kanera には 2 種類の API キーがあります。認証方法は同じですが、アクセスモデルが異なります。

キーの種類	から作成します	こんなときに使います	アクセスモデル
個人用APIキー	プロファイル設定 -> API キー	独自のスクリプト、CLI、または MCP クライアントを接続しており、それを個人的にアクセスできるボード全体で動作させたいと考えています。	アクセスできるすべてのワークスペースとボードにわたって、各ボードでの役割を尊重し、あなたとして行動します。その読むまたは書くスコープは、そのアクセス内で実行できる内容を制限します。ワークスペース管理アクションは実行できません。
ワークスペースまたはボードの API キー	ワークスペース設定 -> API またはボード設定 -> API	1 つのワークスペースまたはスタンドアロンボードに対して、チーム統合、サービスアカウント、Webhook プロデューサー、同期ジョブ、または自動化を設定しています。	そのワークスペースまたはスタンドアロンボードをスコープとします。その読む, 書く、または管理者スコープは統合で何ができるかを制御します。

ユーザー所有のワークフローには個人キーを使用します。宛先で所有、ローテーション、監査する必要がある共有または運用統合には、スコープ指定されたワークスペースまたはボードキーを使用します。

プランの要件

個人の API キーとインタラクティブな AI エージェント接続が機能します あらゆる計画、ホストされた無料を含む。彼らは現在のユーザーとして機能するため、無料組織でもプロ組織でも同様に、ユーザーが開くことができるボードに正確に到達します。

ワークスペースとボードの API キー、無人 OAuth サービスエージェント、Webhook、およびチャット宛先に必要なもの Pro または30日間 プロトライアル。これらは、誰もサインインしていなくても組織に代わって実行されるため、ホストされた無料版では利用できません。作成フォームが表示される代わりに、ワークスペース設定ページでこれについて説明されます。プラン制限の返却によりブロックされたリクエスト 403 次のエラーコードを返します： PLAN_LIMITしたがって、統合により、プランの問題と権限の問題を区別できます。

ワークスペースまたはボードの API キー、OAuth クライアント、チャット宛先のニーズの作成 ワークスペース管理者 許可。管理者は、ワークスペース内のすべての Webhook エンドポイントも管理します。書き込み可能な API 資格情報または対話型 OAuth エージェントは、そのユーザーがワークスペースメンバーである場合、独自の接続をスコープとするエンドポイントを登録できます。個人用 API キーを作成するためにワークスペースロールは必要ありません。

門は創造だけにあるわけではありません。ホストされている組織が Free に移行すると、Kanera はアクティブなワークスペースとボードの API キーを取り消します。これにより、それらに構築された OAuth サービスエージェントも無効になります。 /api/v1 はリクエスト時にそれらを拒否するため、他の場所に残っているキーは依然として使用できません。個人用 API キーと対話型エージェント接続は引き続き機能します。 Webhook エンドポイントとチャット宛先は、同じダウングレードによって一時停止されます。 Pro にアップグレードして戻すと、ダウングレードで影響を受けたキーとエンドポイントが復元されます。

レート制限

API キーおよび AI エージェントからのリクエストは、REST および MCP 経由でも同様に、アクセスされるボードを所有する組織のプラン制限でユーザーごとに制限されます。

ボードの組織	毎秒	1分あたり
ホスト型無料	5	60
ホストされた Pro または Pro トライアル	20	400
自己ホスト型	20	400 (構成可能)

無料組織とプロ組織の両方に所属するユーザーは、独自のボードで各組織の制限を受けます。制限を超えたリクエストはすぐには拒否されません。最大 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チェック、ダッシュボードなど、常に監視できない場所で認証情報を使う場合です。読み取り専用キーで一覧、取得、検索、報告を行えますが、変更操作はすべて次の応答で拒否されます： 403 そしてエラーコード FORBIDDEN。拒否はクライアントではなく API で発生するため、不正な動作をしたエージェントやプロンプトが挿入されたエージェントが作業を変更することはできません。

スコープはキーの作成時に固定されます。変更するには、新しいキーを作成し、古いキーを取り消します。

その秘密は一度公開されます。それをローカルシークレットマネージャー、MCP クライアント設定、または環境変数に保存します。

ワークスペースまたはボードの API キーを作成する

ワークスペースまたはスタンドアロンボードを開きます。
に行く ワークスペース設定 -> API または ボード設定 -> API.
ワークスペース API キーを作成します。
統合に適合する最小のスコープを選択します。
シークレットが表示されたらコピーします。

ワークスペース API キーはワークスペーススコープです。キーは、キーが作成され、作成者がまだアクセスできるワークスペース内のリソースにのみアクセスできます。

その秘密は一度公開されます。それを統合のシークレットマネージャーまたは環境変数に保存します。

ワークスペース API キーのスコープ

範囲	こんなときに使います
読む	統合では、Kanera データの読み取り、検索、レポート、またはエクスポートのみが必要です。
書く	統合では、カード、コメント、ラベル、担当者、カスタムフィールド値、メモ、添付ファイルなどの作業を作成または更新する必要があります。
管理者	統合には、サポートされている場合、管理者レベルのパブリック API 操作が必要です。これは慎重に使用してください。

読む, 書く、そして 管理者 ワークスペースキーとボードキーに適用されます。個人キーは以下から選択します読むそして書くのみであり、常にそれに加えて所有者のボードレベルの権限を継承します。

個別の統合には個別の API キーを使用します。これにより、アクセスの取り消し、ローテーション、監査が容易になります。共有システムの場合は、アクセスが 1 人の個人ツールに関連付けられないように、ワークスペースキーを優先します。

認証

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 エージェントは、API キーを保存する代わりに、ブラウザーの同意またはサービス接続を通じてKanera MCP に接続できます。

OAuth 接続は MCP 用です。これは一般に公開されている API 認証情報ではありません。独自の統合で呼び出す必要がある場合は、個人、ワークスペース、またはボードの API キーを使用します。 /api/v1 直接的に。

OAuth パスは 3 つあります。

インタラクティブエージェント PKCE付きの認可コードフローを使用します。ブラウザーで一度接続を承認すると、エージェントはそのユーザーとして操作します。Claude、ChatGPT、Copilot、Codexなどの対応MCPクライアントは、この方法でAPIキーなしで接続できます。
デバイスクライアント デバイス認可グラントを使用します（urn:ietf:params:oauth:grant-type:device_code）。クライアントは短いコードを表示し、ユーザーは任意のデバイスのブラウザでそれを承認し、クライアントはトークンをポーリングします。これは、ブラウザのリダイレクトを受信できない CLI またはヘッドレスクライアントに使用します。を参照してください。デバイス認証リファレンス.
無人エージェント 使用するもの： client_credentials 助成金。クライアント ID とシークレットを作成します。 ワークスペース設定 -> API ブラウザーを操作することなく、それらを短期間のトークンと交換します。これらは CI、cron、またはサーバー側エージェントに使用します。

参照 AIエージェントを接続するセットアップ、スコープ、接続管理用。カスタム OAuth クライアントの作成者は、次の場所でプロトコルの詳細を確認できます。 MCP 技術リファレンス.

ベース URL とバージョン管理

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 したがって、カードは完全に記述された状態で到着し、ラベルの自動化が 1 回実行されます。

1 つのボードでリクエストごとに最大 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"

解決では大文字と小文字は区別されず、カードの現在の ID、ワークスペース、ボード、リスト、番号、キー、ブラウザ URL が返されます。組織キーは、Kanera によって返される不透明な値であり、組織名やスラッグではありません。紛失したカードとアクセスできないカードは両方とも返却されます 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}'

ボードセパレータの管理

セパレーターは、ワークフローリストのカードとセパレーターの混合順序レーンにある、ボードが所有する、タイトルが付いた、オプションで色の付いたアイテムです。正確に型指定されたアンカーに 1 つを作成します。

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 正確に 1 つを指定してください beforeItem または afterItem;アイテムは { "type": "card", "id": "..." } または { "type": "separator", "id": "..." } 参考。あ null afterItem 頂上とを意味します null beforeItem 底を意味します。セパレータを削除すると、カードは変更されません。

次の注文を管理する

API は、ホーム、マイカード、およびチームカードで使用されるのと同じランク付けされたキューを公開します。

エンドポイント	使用する
`GET /api/v1/work/priority-targets`	資格情報がキューを読み取る可能性があるユーザーをリストします。
`GET /api/v1/work/priorities`	1 つの応答で許可されたすべてのキューを読み取ります。
`GET /api/v1/work/priorities/{userId}`	1 つのキューをランク順に読み取ります。
`POST /api/v1/work/priorities/{userId}/cards`	割り当てられたアクティブカードをアンカー位置に追加します。
`POST /api/v1/card-priorities/{id}/move`	1 つのキューエントリを別の表示可能なエントリの前後に移動します。
`DELETE /api/v1/card-priorities/{id}`	カードを変更せずにエントリを削除します。

個人の資格情報はいつでも自分自身のキューを読み取ることができます。他の人のキューを読み取るには、共有ワークスペース内で有効な管理者権限が必要です。書き込みには、書き込み可能な資格情報とターゲットカードの権限も必要です。キューから返されたエントリ ID を移動アンカーとして使用します。ランクはプレゼンテーション値であり、突然変異 ID ではありません。

ファイルの添付と読み取り

POST /api/v1/cards/{id}/attachments マルチパートアップロードが必要です。 AI エージェントのサンドボックスなど、呼び出し元が直接ストリーミングできない場所にファイルが存在する場合は、代わりに 1 回限りのアップロードリンクを作成し、 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 (最大1200px)または ?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 それ以降に行われた編集を上書きする代わりに。スクラッチパッドは 1 人のユーザーに属しているため、ワークスペース 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 は、将来、最大 56 日 (8 週間) 先の、オフセットのある ISO インスタントです。カードごとに 1 つのリマインダーを保持するため、再度設定すると置き換えられ、再設定されます。開いている他のセッションはすぐに更新されます。視聴もリマインダーもカードのアクティビティには表示されません。参照リマインダー.

GET /api/v1/notifications これは、ラップトップ上で実行されているものなど、Webhook を受信できないスクリプトまたはエージェント用です。通知ドロワーと同じ行 (返信、メンション、割り当て、監視しているカードまたは割り当てられているカードの変更) を古いものから順に返します。何もせずに一度呼び出してください since 最新の行の場合は、各応答の cursor として戻る sinceを繰り返しながら hasMore です true、新しいものだけを取得します。各行には 1 行が含まれます 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}`	1 回の実行を読んでください。
`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 は 2 つのライブ状態です。使用する blocked 質問への回答や承認など、人の対応を待っている間はカードのチップが黄色になります。
succeeded, failed、そして cancelled 端末です。ターミナルステータスにより実行が終了し、不変になります。 PATCH 返品 409 次を使用： message: agent run has already ended.
stalled ライブ実行で 15 分間ハートビートが停止すると、ユーザーではなく Kanera によって設定されるため、クラッシュしたエージェントが「動作中」と表示されたカードを無期限に残すことはできません。停止した実行は終了しません。エージェントは依然として終了ステータスでそれを閉じるか、または設定する可能性があります。 running 再開します。

毎 PATCH 何も変更しないものも含めてハートビートを更新するため、長いジョブでは 15 分のウィンドウ内にキープアライブを送信します。ランニーズボードの開始または更新 編集者 他のカードへの書き込みとまったく同様に、アクセスと書き込み可能な資格情報が必要です。実行でも agentRun:started そして agentRun:updated Webhookイベント.

経由で接続されたエージェント OAuth は、ユーザーに代わって動作するエージェントとして記録されます。その実行、コメント、およびアクティビティ行にはエージェントの名前が含まれ、エージェントが動作する人にはエージェントの行動が通知されます。独自のスクリプトで使用される個人 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 ボードとそのリスト、カード、メンバー、ラベル、カスタムフィールドを1回の応答で取得したい場合。
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。少なくとも 1 つの前提条件が不完全でアーカイブされていない間、アクティブなカードはブロックされます。使用する 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 依存関係ビューの背後にあるグラフを読み取ります。スコープを 1 つだけ渡します。

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

あるいはパスする { "workspaceId": "<workspace UUID>" } または { "cardIds": ["<card UUID>"] }。カード ID スコープは 1 ～ 2,000 の UUID を受け入れます。この POST は副作用のない読み取りです。

応答には、コンパクトなカードの概要、エッジ、ボード/リスト/ラベル/人物の検索、カード表面のカスタムフィールド、および truncated。各カードが追加します inScope そしてその正規化 url。各ボードには以下が含まれます canEdit 呼び出し元の依存関係編集権限。あ blocks エッジはから実行されます sourceCardId (前提条件) ～ targetCardId （扶養家族） relates_to 対称です。

ウォークは、関係性を持つオープンでアーカイブされていないスコープカードから始まり、読み取り可能なボード間で双方向にブロッキングエッジをたどり、完成したカードで停止します。関連する近隣ノードはシードから 1 ホップ含まれます。アクセスできないカードは省略されています。 blockedByCount アクティブなブロッカーをまだカウントしています。グラフは 400 カードとセットで停止します truncated: true;完全なチェーンが必要な場合は範囲を狭めます。ワークスペースの資格情報はワークスペース内に残ります。

参照依存関係ビューアプリがこのデータを表示および編集する方法について説明します。 MCP は、これらのコンパクトな概要ではなく、拡張されたエージェント指向の予測を返します。

ボードとワークスペースのモデル

Kanera の API は、次の両方のユーザー向けモデルを表します。

標準のワークスペースには複数のボードが含まれています。
スタンドアロンボードは次のように返されます。 kind: "board" バッキングコンテナを公開するエンドポイントによって実行されますが、ユーザーはそれを 1 つの独立したボードとして体験します。
ボードにはカードが入っています。
リスト、ラベル、カスタムフィールドはスタンドアロンボードにのみ属するか、標準ワークスペース内のすべてのボード間で共有されます。
割り当てエンドポイントは、ワークスペース内のボード全体に割り当てられたカードを返すことができます。
プライベートボードは、API キーがアクセスできる場合にのみ表示されます。
個人キーは、その所有者がアクセスできるワークスペース全体のボードを参照できます。
ワークスペースキーは、その 1 つのワークスペース内のボードのみを表示できます。

これは統合を構築する際に重要です。スキーマを独立させておく必要がある場合は、スタンドアロンボードを使用します。ワークスペースでは、既存のリストとフィールドを再利用して、レポート、割り当てクエリ、カスタムフィールドの集計の一貫性を保ちます。 Global Work UI は、サインインしたユーザーがアクセスできるすべてのボードにまたがることができますが、ワークスペース API キーのスコープは 1 つのワークスペースのままです。

ページネーションとエラー

ページネーションの使用をサポートするエンドポイントをリストします。

パラメータ	意味
`limit`	返されるレコードの数。
`before`	タイムスタンプより前のレコードに対するカーソルスタイルのフィルター。

エラーは次のような JSON を返します。

フィールド	意味
`code`	安定したエラーコード。
`message`	人間が判読できるエラーメッセージ。
`issues`	オプションの検証の詳細。

再試行するか、入力を修正するか、管理者にアクセスの更新を依頼するかを決定する場合は、HTTP ステータスコードとエラーコードを組み合わせて使用します。

Webhook

Webhook を使用すると、Kanera で作業が変更されたときに外部システムが反応できるようになります。参照 Webhook セットアップ、配信検証、サポートされている Webhook イベントタイプの完全なリストについては、

カードのアクティビティをチームチャットチャネルに投稿することが目的の場合は、何も構築する必要はありません。チャットの宛先 Slack、Discord、Telegram、または Zulip の場合。

外部リンク

外部リンクを使用すると、統合では、Kanera レコードと別のシステムのレコード間の永続的なマッピングを保存できます。

同期ジョブを冪等にする必要がある場合は、外部リンクを使用します。たとえば、Trello 同期は、カードの説明に非表示の統合メタデータを含めることなく、どのKanera カードがどの Trello カードにマッピングされているかを記憶できます。

セキュリティに関する推奨事項

統合ごとに 1 つの API キーを使用します。
機能する最も低いスコープを使用します。
キーと Webhook シークレットをシークレットマネージャーに保存します。
従業員が退職したりシステムが変更されたりしたときに、キーと Webhook シークレットをローテーションします。
API キーをスクラッチパッド、メモ、カード、コメント、ソース管理、ログ、またはスクリーンショットに置かないでください。
ペイロードを処理する前に Webhook 署名を検証します。
配信が再試行される可能性があるため、Webhook ハンドラーをべき等にします。
シークレットを記録せずに同期動作をデバッグするのに十分なリクエスト ID とイベント ID を記録します。

構築できるもの​

オフィシャルクライアント​

APIリファレンス​

エンドポイント参照を使用する​

エンドポイントグループ​

API キーのタイプを選択してください​

プランの要件​

レート制限​

個人用 API キーを作成する​

読み取り専用の個人キー​

ワークスペースまたはボードの API キーを作成する​

ワークスペース API キーのスコープ​

認証​

AI エージェント用の OAuth​

ベース URL とバージョン管理​

最初のリクエスト​

ボードセパレータの管理​

次の注文を管理する​

ファイルの添付と読み取り​

スクラッチパッドにキャプチャする​

カードを監視してリマインダーを設定する​

エージェントの実行中の作業を追跡する​

インテグレーションから Webhook を登録する​

信頼性の高い統合フロー​

カード関係​

依存関係グラフ​

ボードとワークスペースのモデル​

ページネーションとエラー​

Webhook​

外部リンク​

セキュリティに関する推奨事項​

関連ページ​