Denser Retriever API

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

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:

echo $DENSER_API_KEY

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

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.

Common Workflows

1. Build a Knowledge Base from Files

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

Step 1: Create a knowledge base

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:

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):

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

c) Trigger import processing:

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

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 is "processed". If "failed" or "timeout", report the error.

Step 4: Search

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

For plain text that doesn't need file upload:

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

Omit knowledgeBaseIds to search everything:

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:

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

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

Supported File Types

PDF, DOCX, PPTX, XLS, XLSX, HTML, TXT, CSV, XML, Markdown. Max file size: 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.