Tornevall Networks

← Back to docs

Knowledge Base API

Last updated: 2026-07-31

Knowledge Base API

This is the single consolidated Knowledge Base document for the English docs tree.

What it is

The Knowledge Base API stores support cases and reusable solutions with optional AI-enriched fields.

  • Private and public entries
  • Full-text search
  • CRUD operations
  • Batch ingest from integrations
  • Per-user statistics

Authentication

Use header-based auth:

  • User endpoints: Authorization: Bearer YOUR_JWT_TOKEN
  • Webhook ingest endpoints: X-Knowledge-Base-API-Key: YOUR_API_KEY

Base URL

/api/v1/knowledge-base

Endpoints

User-scoped endpoints (JWT required)

  • GET /api/v1/knowledge-base - list own entries (page, per_page, search)
  • POST /api/v1/knowledge-base - create entry
  • GET /api/v1/knowledge-base/{id} - get one owned entry
  • PATCH /api/v1/knowledge-base/{id} - update owned entry
  • DELETE /api/v1/knowledge-base/{id} - soft delete owned entry
  • GET /api/v1/knowledge-base/stats - entry stats for current user

Public endpoints (no auth)

  • GET /api/v1/knowledge-base/public
  • GET /api/v1/knowledge-base/public/{id}

Integration/webhook endpoints (API key required)

  • POST /api/v1/knowledge-base/webhook/ingest - single entry ingest
  • POST /api/v1/knowledge-base/webhook/batch - batch ingest (up to 50 entries)

Entry payload

{
  "title": "Password reset: email not delivered",
  "raw_content": "Original support content",
  "raw_metadata": {
    "source_url": "https://support.example.test/tickets/123"
  },
  "ai_interpreted_problem": "User does not receive reset email",
  "ai_interpreted_solution": "Verify mailbox filters and resend token",
  "ai_summary": "Reset flow recovered after mailbox checks",
  "ai_keywords": ["password", "mail", "reset"],
  "source_type": "manual",
  "source_data": {
    "session_id": "example-session-id"
  },
  "is_public": false
}

Quick setup

  1. Run migrations for the project.
  2. Ensure Knowledge Base routes are available.
  3. Generate or assign an API key for webhook integration.
  4. Test one create/list flow with JWT.

Quick test flow

# Create
curl -X POST https://tools.tornevall.net/api/v1/knowledge-base \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test entry","raw_content":"Test","source_type":"manual"}'

# List
curl https://tools.tornevall.net/api/v1/knowledge-base \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Public list
curl https://tools.tornevall.net/api/v1/knowledge-base/public

Integration example (webhook ingest)

await fetch('https://tools.tornevall.net/api/v1/knowledge-base/webhook/ingest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Knowledge-Base-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    title: 'Support session #123',
    raw_content: '<html>...</html>',
    ai_interpreted_problem: 'User cannot sign in',
    ai_interpreted_solution: 'Reset password and confirm mailbox',
    source_type: 'copilot',
    is_public: false
  })
});

Notes

  • Keep sensitive ticket/customer content private by default.
  • Publish only sanitized entries to public mode.
  • Prefer concise, searchable titles and summaries for long-term reuse.