denser-retriever

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Denser Retriever API

Manage knowledge bases and perform semantic search over documents via the Denser Retriever REST API. All operations use

curl

commands.

通过Denser Retriever REST API管理知识库并对文档执行语义搜索。所有操作均使用

curl

命令。

Setup

配置

API Key: Read from

DENSER_API_KEY

environment variable. If not set, ask the user for their API key.

Base URL:

https://retriever.denser.ai/api/open/v1

To check if the key is available:

bash

echo $DENSER_API_KEY

If empty, ask the user: "Please provide your Denser Retriever API key (from your organization settings)."

API Key：从

DENSER_API_KEY

环境变量读取。如果未设置，请向用户索要其API密钥。

基础URL：

https://retriever.denser.ai/api/open/v1

检查密钥是否可用：

bash

echo $DENSER_API_KEY

如果为空，请询问用户："请提供您的Denser Retriever API密钥（可从组织设置中获取）。"

Quick Reference

快速参考

Operation	Method	Endpoint
Get usage	GET	`/v1/getUsage`
Get balance	GET	`/v1/getBalance`
Create KB	POST	`/v1/createKnowledgeBase`
List KBs	GET	`/v1/listKnowledgeBases`
Update KB	POST	`/v1/updateKnowledgeBase`
Delete KB	POST	`/v1/deleteKnowledgeBase`
Upload file (presign)	POST	`/v1/presignUploadUrl`
Import file	POST	`/v1/importFile`
Import text	POST	`/v1/importTextContent`
List documents	GET	`/v1/listDocuments`
Delete document	POST	`/v1/deleteDocument`
Check doc status	GET	`/v1/getDocumentStatus`
Search/query	POST	`/v1/query`

For full request/response schemas, read

references/api_reference.md

操作	方法	端点
查看使用情况	GET	`/v1/getUsage`
查看余额	GET	`/v1/getBalance`
创建知识库	POST	`/v1/createKnowledgeBase`
列出知识库	GET	`/v1/listKnowledgeBases`
更新知识库	POST	`/v1/updateKnowledgeBase`
删除知识库	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

。

Common Workflows

常见工作流

1. Build a Knowledge Base from Files

1. 从文件构建知识库

This is a multi-step process: create KB, upload each file, wait for processing, then search.

Step 1: Create a knowledge base

bash

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

Save the returned

id

for subsequent operations.

Step 2: For each file, do a 3-step upload

a) Get a presigned upload URL:

bash

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) Upload the file to the presigned URL (raw bytes, PUT request):

bash

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

c) Trigger import processing:

bash

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

Step 3: Poll until processed

bash

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

Repeat every 2-3 seconds until

status

"processed"

. If

"failed"

"timeout"

, report the error.

Step 4: Search

bash

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

这是一个多步骤流程：创建知识库、上传每个文件、等待处理完成，然后进行搜索。

步骤1：创建知识库

bash

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：对每个文件执行三步上传流程

a) 获取预签名上传URL：

bash

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请求）：

bash

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

c) 触发导入处理：

bash

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：轮询直至处理完成

bash

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

每2-3秒重复一次，直到

status

变为

"processed"

。如果状态为

"failed"

或

"timeout"

，请报告错误。

步骤4：搜索

bash

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. Import Text Content Directly

2. 直接导入文本内容

For plain text that doesn't need file upload:

bash

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

对于无需文件上传的纯文本：

bash

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. Search Across All Knowledge Bases

3. 跨所有知识库搜索

Omit

knowledgeBaseIds

to search everything:

bash

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

省略

knowledgeBaseIds

参数即可搜索全部内容：

bash

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

Automation Patterns

自动化模式

Batch Upload Multiple Files

批量上传多个文件

When the user provides a directory of files, loop through them:

bash

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

当用户提供文件目录时，可循环处理所有文件：

bash

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

Poll Document Status Until Ready

轮询文档状态直至就绪

bash

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

bash

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

Response Format

响应格式

All responses follow this structure:

Success:

{"success": true, "data": { ... }}

Error:

{"success": false, "message": "Error details", "errorCode": "ERROR_CODE"}

Common error codes:

STORAGE_LIMIT_EXCEEDED

KNOWLEDGE_BASE_LIMIT_EXCEEDED

INSUFFICIENT_CREDITS

INPUT_VALIDATION_FAILED

所有响应均遵循以下结构：

成功响应：

{"success": true, "data": { ... }}

错误响应：

{"success": false, "message": "Error details", "errorCode": "ERROR_CODE"}

常见错误代码：

STORAGE_LIMIT_EXCEEDED

、

KNOWLEDGE_BASE_LIMIT_EXCEEDED

、

INSUFFICIENT_CREDITS

、

INPUT_VALIDATION_FAILED

Supported File Types

支持的文件类型

PDF, DOCX, PPTX, XLS, XLSX, HTML, TXT, CSV, XML, Markdown. Max file size: 512MB.

PDF、DOCX、PPTX、XLS、XLSX、HTML、TXT、CSV、XML、Markdown。最大文件大小：512MB。

Important Notes

重要说明

Each search query costs 1 credit. Check balance with
```
getBalance
```
before bulk searches.
Document processing is async — always poll
```
getDocumentStatus
```
before searching.
The
```
presignUploadUrl
```
-> PUT upload ->
```
importFile
```
flow is required for file uploads.
Search results include
```
score
```
,
```
content
```
,
```
title
```
,
```
document_id
```
, and
```
metadata
```
.

每个搜索查询消耗1个点数。批量搜索前请使用
```
getBalance
```
查看余额。
文档处理为异步操作——搜索前务必调用
```
getDocumentStatus
```
轮询状态。
文件上传必须遵循
```
presignUploadUrl
```
-> PUT上传 ->
```
importFile
```
的流程。
搜索结果包含
```
score
```
、
```
content
```
、
```
title
```
、
```
document_id
```
和
```
metadata
```
。