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

|User Intent |Endpoint |Key Params | |---|---|---| |List knowledge bases |GET /knowledge-bases |— | |View KB details |GET /knowledge-bases/:id |— | |Upload a file |POST /knowledge-bases/:id/knowledge/file |file (form-data), enable_multimodel | |Import a web page |POST /knowledge-bases/:id/knowledge/url |url, enable_multimodel | |Write Markdown content |POST /knowledge-bases/:id/knowledge/manual |title, content, tag_id | |Check upload progress |GET /knowledge/:id |watch parse_status | |Browse KB contents |GET /knowledge-bases/:id/knowledge |page, page_size, tag_id | |Edit Markdown knowledge |PUT /knowledge/manual/:id |title, content | |Delete a knowledge entry |DELETE /knowledge/:id |— | |Search within a KB |GET /knowledge-bases/:id/hybrid-search |query_text, match_count, thresholds | |Search across KBs |POST /knowledge-search |query, knowledge_base_ids |

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\n\nKey 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"
  }
}

|HTTP Code |Meaning |Suggested Action | |---|---|---| |400 |Bad request |Check required fields and param formats | |401 |Unauthorized |Verify WEKNORA_API_KEY is correct | |403 |Forbidden |Confirm you have access to this resource | |404 |Not found |Check resource ID exists | |413 |Payload too large |Reduce file size or split content | |500 |Server error |Retry after a short delay |