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

|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//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/"
-> repeat until data.parse_status == "completed"

Import URL

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

Search Knowledge

# Single-KB hybrid search (vector + keyword)
wk_api GET "knowledge-bases//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//knowledge?page=1&page_size=20"
Get full detail of one entry
wk_api GET "knowledge/"

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

Pagination

Notes

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 |

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.