ナレッジに API で資料を登録する

画面から1つずつアップロードする代わりに、自社のサーバーからナレッジに資料を登録できます。基幹システムにある規程・マニュアル・FAQ を定期的に取り込む、といった使い方を想定しています。

準備するもの

キーは暗号化して保存されるので、ワークスペース設定 → ナレッジ API の キーをコピー であとからコピーし直せます。再発行 すると、それまでのキーは無効になります。以前に発行したキーに knowledge:read が付いていても、エラーにはならず、何にも使われません。

アプリの API Server で発行する bkapi_ キーでも、/apps/{appId}/knowledge/documents に登録できます。キーの発行画面で ナレッジへの資料登録を許可 をオンにしてください。そのキーで登録した資料には、どのアプリから登録されたかが記録されます。

ベース URL と認証

ベース URL は、ワークスペース設定 → ナレッジ API の「API でアップロードする」に、ワークスペース ID が入った状態で表示されます。以降の例では $BASE と書きます。

BASE="https://api.platio-canvas-ai.com/api/data/v1/workspaces/{workspaceId}/knowledge"

すべてのリクエストに Authorization: Bearer bkws_… ヘッダーを付けます。エラーは RFC 9457 の形式で返ります。code を見て分岐してください。

登録の手順

multipart の file フィールドに、ファイルを1件入れて POST /documents を呼びます。

curl -X POST "$BASE/documents" \
  -H "Authorization: Bearer bkws_xxxxxxxx" \
  -F "file=@manual.pdf"

フォルダに入れるときは -F "folder_id=<フォルダの ID>" を足します。フォルダの ID は、ワークスペース設定 → ナレッジ API の「API でアップロードする」でフォルダを選ぶと、コピーするコマンドに入ります。対応している形式とサイズの上限（1ファイル25MBまで、画像は5MBまで）は、画面からのアップロードと同じです（ナレッジにファイルを登録する）。

Content-Type は自分で指定しないでください。curl などのクライアントが、区切り文字（boundary）を含めて自動で付けます。

レスポンス

受け付けると 202 が返ります。返るのは登録した資料の id・題名・状態などの情報だけで、本文は返りません。

{
  "document": {
    "id": "8f0c…",
    "title": "manual",
    "filename": "manual.pdf",
    "source_type": "file",
    "status": "processing",
    "error": null,
    "chunk_count": 0,
    "size_bytes": 482133,
    "folder_id": null,
    "created_at": "2026-10-14T01:23:45.000Z",
    "updated_at": "2026-10-14T01:23:45.000Z"
  }
}

登録した直後の status は processing です。テキストの読み取りと検索の準備は、そのあと自動で進みます。進み具合やエラーは、ナレッジ画面の一覧で確認してください。

同じファイルを送り直すと二重に登録されます

登録は既存の資料を上書きしません。同じファイルをもう一度送ると、別の資料として二重に登録されます。資料を新しくしたいときは、古い資料をナレッジ画面から削除してから登録し直してください。API から資料を削除することはできません。

IP アドレス制限

ワークスペースで IP アドレス制限を設定すると、許可していないアドレスからの呼び出しは 403 ip_not_allowed で拒否されます。bkws_ キーと bkapi_ キーのどちらにも同じ制限がかかります。設定は ワークスペース設定 → ナレッジ API の「IP アドレス制限」で行います（オーナー・管理者）。

レート制限

1時間あたりの回数に上限があります。bkws_ キーはワークスペース単位、bkapi_ キーはアプリ単位で数えます。キーを何本発行しても、上限の合計は変わりません。

登録は1回で書き込み25回分として数えます（テキストの読み取りと検索の準備に時間がかかるため）。上限を超えると 429 と Retry-After（待つ秒数）が返ります。各レスポンスの RateLimit-Remaining で残りの回数がわかります。

エラー