denser-retriever

Denser Retriever API

Denser Retriever REST API を使用してナレッジベースを管理し、ドキュメントのセマンティック検索を実行します。すべての操作で curl コマンドを使用します。

セットアップ

API キー：DENSER_API_KEY 環境変数から読み取ります。設定されていない場合は、ユーザーに API キーを尋ねてください。

ベース URL：https://retriever.denser.ai/api/open/v1

キーを利用できるか確認するには：

echo $DENSER_API_KEY

空の場合は、ユーザーに「Denser Retriever の API キー（組織の設定から取得）を入力してください。」と尋ねてください。

クイックリファレンス

操作	メソッド	エンドポイント
使用量を取得	GET	/v1/getUsage
残高を取得	GET	/v1/getBalance
KB を作成	POST	/v1/createKnowledgeBase
KB を一覧表示	GET	/v1/listKnowledgeBases
KB を更新	POST	/v1/updateKnowledgeBase
KB を削除	POST	/v1/deleteKnowledgeBase
ファイルをアップロード（事前署名）	POST	/v1/presignUploadUrl
ファイルをインポート	POST	/v1/importFile
テキストをインポート	POST	/v1/importTextContent
ドキュメントを一覧表示	GET	/v1/listDocuments
ドキュメントを削除	POST	/v1/deleteDocument
ドキュメントのステータスを確認	GET	/v1/getDocumentStatus
検索／クエリ	POST	/v1/query

リクエスト／レスポンスの完全なスキーマについては、references/api_reference.md を参照してください。

一般的なワークフロー

1. ファイルからナレッジベースを構築する

複数の手順で行います。KB を作成し、各ファイルをアップロードして、処理が完了するまで待ってから検索します。

手順 1：ナレッジベースを作成する

curl -s -X POST "https://retriever.denser.ai/api/open/v1/createKnowledgeBase" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My KB", "description": "Optional description"}' | python3 -m json.tool

後続の操作で使用するため、返された id を保存します。

手順 2：各ファイルについて、3 つの手順でアップロードする

a) 事前署名付きアップロード URL を取得します：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/presignUploadUrl" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId": "KB_ID", "fileName": "document.pdf", "size": FILE_SIZE_BYTES}' | python3 -m json.tool

b) 事前署名付き URL にファイルをアップロードします（生のバイト列、PUT リクエスト）：

curl -s -X PUT "PRESIGNED_UPLOAD_URL" --data-binary @/path/to/document.pdf

c) インポート処理を開始します：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/importFile" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "FILE_ID"}' | python3 -m json.tool

手順 3：処理が完了するまでポーリングする

curl -s -X GET "https://retriever.denser.ai/api/open/v1/getDocumentStatus?documentId=DOC_ID" \
  -H "x-api-key: $DENSER_API_KEY" | python3 -m json.tool

status が "processed" になるまで 2～3 秒ごとに繰り返します。"failed" または "timeout" の場合は、エラーを報告します。

手順 4：検索する

curl -s -X POST "https://retriever.denser.ai/api/open/v1/query" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query", "knowledgeBaseIds": ["KB_ID"], "limit": 10}' | python3 -m json.tool

2. テキストコンテンツを直接インポートする

ファイルのアップロードが不要なプレーンテキストの場合：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/importTextContent" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledgeBaseId": "KB_ID", "title": "My Document", "content": "Full text content here..."}' | python3 -m json.tool

3. すべてのナレッジベースを横断して検索する

すべてを検索するには、knowledgeBaseIds を省略します：

curl -s -X POST "https://retriever.denser.ai/api/open/v1/query" \
  -H "x-api-key: $DENSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query", "limit": 10}' | python3 -m json.tool

自動化パターン

複数ファイルの一括アップロード

ユーザーからファイルのディレクトリが指定された場合は、次のようにループ処理します：

KB_ID="your-kb-id"
for file in /path/to/files/*; do
  FILE_NAME=$(basename "$file")
  FILE_SIZE=$(stat -f%z "$file" 2>/dev/null || stat -c%s "$file" 2>/dev/null)

  # Get presigned URL
  PRESIGN=$(curl -s -X POST "https://retriever.denser.ai/api/open/v1/presignUploadUrl" \
    -H "x-api-key: $DENSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"knowledgeBaseId\": \"$KB_ID\", \"fileName\": \"$FILE_NAME\", \"size\": $FILE_SIZE}")

  UPLOAD_URL=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['uploadUrl'])")
  FILE_ID=$(echo "$PRESIGN" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['fileId'])")

  # Upload file
  curl -s -X PUT "$UPLOAD_URL" --data-binary @"$file"

  # Trigger import
  curl -s -X POST "https://retriever.denser.ai/api/open/v1/importFile" \
    -H "x-api-key: $DENSER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"fileId\": \"$FILE_ID\"}"

  echo "Uploaded: $FILE_NAME (fileId: $FILE_ID)"
done

準備ができるまでドキュメントのステータスをポーリングする

DOC_ID="your-document-id"
while true; do
  STATUS=$(curl -s -X GET "https://retriever.denser.ai/api/open/v1/getDocumentStatus?documentId=$DOC_ID" \
    -H "x-api-key: $DENSER_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['status'])")
  echo "Status: $STATUS"
  if [ "$STATUS" = "processed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "timeout" ]; then
    break
  fi
  sleep 3
done

レスポンス形式

すべてのレスポンスは次の構造に従います：

成功： {"success": true, "data": { ... }}

エラー： {"success": false, "message": "Error details", "errorCode": "ERROR_CODE"}

一般的なエラーコード：STORAGE_LIMIT_EXCEEDED、KNOWLEDGE_BASE_LIMIT_EXCEEDED、INSUFFICIENT_CREDITS、INPUT_VALIDATION_FAILED

サポートされているファイル形式

PDF、DOCX、PPTX、XLS、XLSX、HTML、TXT、CSV、XML、Markdown。最大ファイルサイズ：512MB。

重要な注意事項

• 検索クエリごとに 1 クレジットを消費します。検索を一括で実行する前に、getBalance で残高を確認してください。
• ドキュメントの処理は非同期です。検索する前に、必ず getDocumentStatus をポーリングしてください。
• ファイルのアップロードには、presignUploadUrl -> PUT アップロード -> importFile のフローが必要です。
• 検索結果には、score、content、title、document_id、metadata が含まれます。