WeKnora API Reference

Complete API documentation for programmatic access to WeKnora services. All API endpoints are RESTful and return JSON responses.

Base URL

All API requests should be made to:

http://localhost:8080/api/v1

For production deployments, replace localhost:8080 with your WeKnora server address.

Authentication

WeKnora API uses API key authentication. Include your API key in the request header:

x-api-key: sk-your-api-key-here

Getting Your API Key

Open your WeKnora instance in a browser
Open browser developer tools (F12)
Check network requests for the x-api-key header
Copy the API key (starts with "sk")

API Endpoints

Knowledge Bases

Method	Endpoint	Description
GET	`/knowledgebases`	List all knowledge bases
POST	`/knowledgebases`	Create a new knowledge base
GET	`/knowledgebases/{id}`	Get knowledge base details
PUT	`/knowledgebases/{id}`	Update knowledge base
DELETE	`/knowledgebases/{id}`	Delete a knowledge base

Documents

Method	Endpoint	Description
POST	`/knowledgebases/{kb_id}/documents`	Upload a document
GET	`/knowledgebases/{kb_id}/documents`	List documents in knowledge base
GET	`/documents/{id}`	Get document details
DELETE	`/documents/{id}`	Delete a document

Search & Retrieval

Method	Endpoint	Description
POST	`/knowledgebases/{kb_id}/search`	Search knowledge base
POST	`/search`	Cross-knowledge base search

Conversations

Method	Endpoint	Description
POST	`/conversations`	Create a new conversation
POST	`/conversations/{id}/messages`	Send a message in conversation
GET	`/conversations/{id}`	Get conversation history

Document Upload

Upload documents to a knowledge base using multipart form data.

Request

POST /api/v1/knowledgebases/{kb_id}/documents
Content-Type: multipart/form-data
x-api-key: sk-your-api-key

file: [binary file data]
tags: ["tag1", "tag2"]  # optional
            

Response

{
  "id": "doc_123",
  "name": "document.pdf",
  "status": "processing",
  "created_at": "2024-01-01T00:00:00Z"
}
            

Search API

Search a knowledge base for relevant information.

Request

POST /api/v1/knowledgebases/{kb_id}/search
Content-Type: application/json
x-api-key: sk-your-api-key

{
  "query": "What is WeKnora?",
  "top_k": 5,
  "threshold": 0.7,
  "rerank": true
}
            

Response

{
  "results": [
    {
      "id": "chunk_123",
      "content": "WeKnora is a document understanding framework...",
      "score": 0.95,
      "document_id": "doc_123",
      "metadata": {
        "page": 1,
        "section": "Introduction"
      }
    }
  ],
  "total": 1
}
            

Conversation API

Create and manage conversations for Q&A.

Create Conversation

POST /api/v1/conversations
Content-Type: application/json
x-api-key: sk-your-api-key

{
  "knowledge_base_ids": ["kb_123"],
  "mode": "agent",  # or "normal"
  "model": "gpt-4",
  "enable_web_search": false
}
            

Send Message

POST /api/v1/conversations/{conversation_id}/messages
Content-Type: application/json
x-api-key: sk-your-api-key

{
  "message": "What is the main feature of WeKnora?",
  "stream": false
}
            

Response

{
  "id": "msg_123",
  "message": "What is the main feature of WeKnora?",
  "response": "WeKnora's main feature is...",
  "sources": [
    {
      "document_id": "doc_123",
      "chunk_id": "chunk_456",
      "score": 0.92
    }
  ],
  "created_at": "2024-01-01T00:00:00Z"
}
            

Go Client Library

WeKnora provides an official Go client library for easy integration.

Installation

go get github.com/Tencent/WeKnora/client

Usage Example

package main

import (
    "context"
    "fmt"
    "github.com/Tencent/WeKnora/client"
)

func main() {
    cfg := &client.Config{
        BaseURL: "http://localhost:8080/api/v1",
        APIKey:  "sk-your-api-key",
    }
    
    c := client.New(cfg)
    
    // Search knowledge base
    results, err := c.Search(context.Background(), "kb_123", &client.SearchRequest{
        Query:    "What is WeKnora?",
        TopK:     5,
        Threshold: 0.7,
    })
    
    if err != nil {
        panic(err)
    }
    
    fmt.Printf("Found %d results\n", len(results))
}
            

Client Documentation

Error Handling

All API errors follow a consistent format:

Error Response

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid API key",
    "details": {}
  }
}
            

HTTP Status Codes

Code	Description
200	Success
201	Created
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

Rate Limiting

API requests are subject to rate limiting to ensure fair usage. Rate limit information is included in response headers:

X-RateLimit-Limit: Maximum requests per window
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Time when rate limit resets

Webhooks

WeKnora supports webhooks for event notifications:

Document processing completion
Knowledge base updates
Error notifications

Configure webhooks in the knowledge base settings.

Additional Resources

API Documentation

View API Examples Read Documentation