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:

bash

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.

bash

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:

bash

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#

User IntentEndpointKey ParamsList knowledge basesGET /knowledge-bases—View KB detailsGET /knowledge-bases/:id—Upload a filePOST /knowledge-bases/:id/knowledge/file``file (form-data), enable_multimodelImport a web pagePOST /knowledge-bases/:id/knowledge/url``url, enable_multimodelWrite Markdown contentPOST /knowledge-bases/:id/knowledge/manual``title, content, tag_idCheck upload progressGET /knowledge/:idwatch parse_statusBrowse KB contentsGET /knowledge-bases/:id/knowledge``page, page_size, tag_idEdit Markdown knowledgePUT /knowledge/manual/:id``title, contentDelete a knowledge entryDELETE /knowledge/:id—Search within a KBGET /knowledge-bases/:id/hybrid-search``query_text, match_count, thresholdsSearch across KBsPOST /knowledge-search``query, knowledge_base_ids

Common Workflows#

Upload File and Wait for Parsing#

bash

# 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#

bash

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#

bash

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

Search Knowledge#

bash

# 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#

bash

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

json

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

HTTP CodeMeaningSuggested Action400Bad requestCheck required fields and param formats401UnauthorizedVerify WEKNORA_API_KEY is correct403ForbiddenConfirm you have access to this resource404Not foundCheck resource ID exists413Payload too largeReduce file size or split content500Server errorRetry after a short delay