weknora
Import documents and perform knowledge retrieval via WeKnora API. Use when uploading files, URLs, or Markdown to a knowledge base, searching knowledge with hybrid retrieval (vector + keyword), or querying knowledge details. Triggers: (1) uploading documents to a knowledge base, (2) hybrid search across knowledge bases, (3) listing/querying knowledge base contents.
How do I install this agent skill?
npx skills add https://clawhub.ai --skill weknoraIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
WeKnora
Knowledge base document import and retrieval through the WeKnora REST API.
Setup
- Get your API Key from the WeKnora web UI (account settings page)
- 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
~/.zshrcor~/.bashrcto 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|failedenable_status:enabled|disabled(knowledge becomesenabledafter 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): usepageandpage_sizequery params. Response includestotalfor calculating pages. - Hybrid search: returns up to
match_countresults (no pagination; increasematch_countfor more).
Notes
GET /knowledge-bases/:id/hybrid-searchuses GET method but requires a JSON request body — pass-d '{...}'with curl.- After uploading, knowledge
enable_statusstarts asdisabledand auto-switches toenabledonceparse_statusreachescompleted. - File upload uses
multipart/form-data, not JSON. Usecurl -F 'file=@path'. file_typeis auto-detected from the uploaded file (supportspdf,docx,xlsx,pptx,txt,md,csv,html, etc.).- Search
scoreranges from 0 to 1; higher is more relevant. Adjustvector_threshold(default ~0.5) to filter low-quality matches. - When
parse_statusisfailed, checkerror_messagefield for the failure reason before retrying withPOST /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 |
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/clawhub.ai/weknora">View weknora on skillZs</a>