Knowledgebase API for Claude agents

How a Claude agent queries the car-repair knowledgebase (Suzuki Vitara/Sidekick, Chevy/Geo Tracker; G16/J-series platform). Retrieval is semantic — ask a natural-language question, get the best manual sections ranked by meaning.

Semantic search endpoint

GET https://knowledgebase.taild4189d.ts.net/api/search
      ?q=<url-encoded natural-language question>   (required)
      &limit=<1-50, default 20>
      &folder=<top folder, optional filter>        e.g. suzuki-vitara | chevy-tracker | kick-fix
      &manual=<manual_id, optional filter>          e.g. suzuki-vitara/workshop-1988-1998

On the box directly: http://127.0.0.1:8092/api/search?q=...

Response

{
  "took_ms": 54,
  "count": 8,
  "hits": [
    {
      "heading": "Pump is dead, now what",
      "manual_id": "kick-fix/ecu",
      "vehicle": "kick-fix",
      "page_url": "/kick-fix/ecu/006-my-ecu-is-bad-now-what/",
      "snippet": "…<mark>fuel pump</mark>… (HTML, query terms highlighted)",
      "score": 0.728,
      "type": "manual"
    }
  ]
}

• score: cosine similarity. Rough guide: ≥0.70 strong, 0.60–0.70 relevant, <0.55 weak.
• type: manual or article (consolidated how-to). Wiring extraction is retired — ignore any wiring content; do not rely on netlists.
  • Scope of that retirement: it kills the AI-extracted netlists (.wiring.json, the wires.txt sidecars, the generated connection tables and Mermaid circuit graphs). The OCR’d scanned diagram pages themselves remain good and are the authoritative scan source for cluzter’s tracing underlays. “Wiring extraction is retired” ≠ “the wiring scans are worthless”.
• page_url: deep link to the section (prefix the host for a full URL).

Reading full page content

/api/search returns a snippet, not the full text. To read a hit in full:

• Rendered page: GET https://knowledgebase.taild4189d.ts.net/<page_url>
• Source markdown (on box): /home/levander/knowledgebase/manuals-src/docs/<page_url without leading/trailing slash>.md

Typical agent loop: search(question) → pick top hits → fetch each page_url (or its .md) → read/cite.

Wiring diagrams (scans, not netlists)

The authoritative wiring source is the scanned diagrams themselves (accurate by construction). A consolidated, curated library of all 480 wiring-diagram scans (5 vehicles, 13 manuals, grouped) lives at:

• https://knowledgebase.taild4189d.ts.net/wiring-gallery/ — each thumbnail links to the full scan in its source page; diagrams are click-to-zoom (full-screen pan/zoom via glightbox).

Use these scans as tracing underlays / ground truth (this is cluzter’s source). The AI-extracted netlists were retired for inaccuracy — do not query /api/search for wiring connectivity; go to the scan.

Example (curl)

curl -s 'https://knowledgebase.taild4189d.ts.net/api/search?q=why+won%27t+the+fuel+pump+prime&limit=5'

Notes / limits

• Content is English (OCR’d manuals). A Hungarian read-only mirror is being built under /hu/<page_url> (partial; falls back to English). Search itself is English-only (bge-large-en embeddings).
• Retrieval only — no answer synthesis. (A cited-answer /api/answer RAG endpoint is a possible future add.)
• Empty q → empty hits. Qdrant down → HTTP 503 (search unavailable; the rest of the site stays up).
• Browse UI: / is the search page; /browse is the manual tree.