weknora（weknora 文档）

WeKnora

Knowledge base document import and retrieval through the WeKnora REST API.

Setup

1. Get your API Key from the WeKnora web UI (account settings page)
2. Configure environment variables:

export WEKNORA_BASE_URL="https://your-server.com/api/v1"
export WEKNORA_API_KEY="sk-your-api-key"

Add the above to ~/.zshrc or ~/.bashrc to persist across sessions.

Credential Check

Verify credentials before any API call. Stop and prompt the user if unset.

if [ -z "$WEKNORA_BASE_URL" ] || [ -z "$WEKNORA_API_KEY" ]; then
  echo "Missing WeKnora credentials. Set WEKNORA_BASE_URL and WEKNORA_API_KEY per Setup."
  exit 1
fi

API Call Template

All requests go to $WEKNORA_BASE_URL with a shared header set. Define a helper:

wk_api() {
  local method="$1" endpoint="$2" body="$3"
  curl -s -X "$method" "$WEKNORA_BASE_URL/$endpoint" \
    -H "X-API-Key: $WEKNORA_API_KEY" \
    -H "Content-Type: application/json" \
    -H "X-Request-ID: $(uuidgen 2>/dev/null || date +%s)" \
    ${body:+-d "$body"}
}

For file uploads use curl -F directly (multipart/form-data).

API Decision Table

Common Workflows

Upload File and Wait for Parsing

# 1. Find target KB
wk_api GET "knowledge-bases"
# -> pick kb_id from data[].id

# 2. Upload file
curl -s -X POST "$WEKNORA_BASE_URL/knowledge-bases/<kb_id>/knowledge/file" \
  -H "X-API-Key: $WEKNORA_API_KEY" \
  -F 'file=@document.pdf' -F 'enable_multimodel=true'
# -> get knowledge_id from data.id

# 3. Poll until parsed
wk_api GET "knowledge/<knowledge_id>"
# -> repeat until data.parse_status == "completed"

Import URL

wk_api POST "knowledge-bases/<kb_id>/knowledge/url" \
  '{"url": "https://example.com/article", "enable_multimodel": true}'
# -> poll knowledge/:id same as file upload

Write Markdown Knowledge

wk_api POST "knowledge-bases/<kb_id>/knowledge/manual" \
  '{"title": "Meeting Notes", "content": "# Q1 Review\
\
Key points..."}'

Search Knowledge

# Single-KB hybrid search (vector + keyword)
wk_api GET "knowledge-bases/<kb_id>/hybrid-search" \
  '{"query_text": "deployment process", "match_count": 5}'

# Cross-KB semantic search
wk_api POST "knowledge-search" \
  '{"query": "deployment process", "knowledge_base_ids": ["kb-1", "kb-2"]}'

Browse and Read KB Contents

# List knowledge entries (paginated)
wk_api GET "knowledge-bases/<kb_id>/knowledge?page=1&page_size=20"

# Get full detail of one entry
wk_api GET "knowledge/<knowledge_id>"

Core Response Fields

Knowledge Base (GET /knowledge-bases): data[] — id, name, description, type (document | faq), embedding_model_id, knowledge_count, chunk_count, is_processing, created_at.

Knowledge Entry (GET /knowledge/:id): data — id, title, description (auto-generated summary), type (file | url | manual), parse_status, enable_status, file_name, file_type, file_size, source (URL origin), created_at, processed_at, error_message.

Search Result (hybrid-search): data[] — id, content (chunk text), score (relevance 0–1), knowledge_id, knowledge_title, knowledge_filename, chunk_index, chunk_type (text | summary | image), match_type, metadata.

Paginated List (GET .../knowledge): data[] + total, page, page_size.

Enum Values

• parse_status: pending → processing → completed | failed
• enable_status: enabled | disabled (knowledge becomes enabled after successful parsing)
• type (knowledge): file (uploaded file), url (web import), manual (Markdown)
• type (knowledge base): document (standard), faq (FAQ pairs)
• chunk_type: text (regular chunk), summary (auto-generated summary), image (image chunk)

Pagination

• Offset pagination (GET .../knowledge, GET /sessions): use page and page_size query params. Response includes total for calculating pages.
• Hybrid search: returns up to match_count results (no pagination; increase match_count for more).

Notes

• GET /knowledge-bases/:id/hybrid-search uses GET method but requires a JSON request body — pass -d '{...}' with curl.
• After uploading, knowledge enable_status starts as disabled and auto-switches to enabled once parse_status reaches completed.
• File upload uses multipart/form-data, not JSON. Use curl -F 'file=@path'.
• file_type is auto-detected from the uploaded file (supports pdf, docx, xlsx, pptx, txt, md, csv, html, etc.).
• Search score ranges from 0 to 1; higher is more relevant. Adjust vector_threshold (default ~0.5) to filter low-quality matches.
• When parse_status is failed, check error_message field for the failure reason before retrying with POST /knowledge/:id/reparse.

Error Handling

All errors return:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": "Optional extra info"
  }
}