Local API Guide contents
Overview
Searches your documents the way the app does: by meaning (Qwen3-Embedding-4B) and by keywords, combined, best first. Passages that don't really match are left out, so you may get fewer than limit, or none. It doesn't generate text, so it doesn't count toward your daily allowance.
Request body
| Parameter | Description |
|---|---|
querystringrequired | A question or keywords. |
collectionstring | all (default), a collection name, or an id like c:3. |
limitinteger | 1 to 40 passages. Default 8. |
| Authorization header | Authorization: Bearer <key>, only when Require API key is on in the app. |
Response
| Field | Description |
|---|---|
query, collectionstring | Your query, and the collection searched (all or c:<id>). |
data[].indexinteger | Rank, from 1. |
data[].document, document_idstring, integer | The file the passage is from. |
data[].collectionstring | Its collection id. |
data[].location, headingstring | Where in the file (page, slide, sheet) and the section heading, when known. |
data[].textstring | The passage. |
data[].similaritynumber | Closeness in meaning to the query (0–1). |
data[].scorenumber | The combined ranking score (meaning and keywords). |
Example
curl http://localhost:1234/v1/knowledge/search \ -H "Content-Type: application/json" \ -d '{"query": "refunds for digital goods", "collection": "Policies", "limit": 5}'
import requests hits = requests.post("http://localhost:1234/v1/knowledge/search", json={"query": "refunds for digital goods", "collection": "Policies", "limit": 5}).json()["data"] for h in hits: print(f"{h['similarity']:.2f} {h['document']} ({h['location']}): {h['text'][:100]}")
const { data } = await (await fetch("http://localhost:1234/v1/knowledge/search", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ query: "refunds for digital goods", collection: "Policies", limit: 5 }), })).json(); data.forEach(h => console.log(h.similarity.toFixed(2), h.document, h.location));
{
"object": "list",
"query": "refunds for digital goods",
"collection": "c:3",
"data": [
{ "index": 1, "document": "Refund policy.pdf", "document_id": 41, "collection": "c:3",
"location": "page 2", "heading": "Digital products",
"text": "Digital goods can be refunded within 14 days if they have not been downloaded…",
"similarity": 0.7412, "score": 0.03252 }
]
}Errors
| Status | Code | When |
|---|---|---|
| 401 | invalid_api_key | Require API key is on and the key is missing or wrong. |
| 400 | invalid_request | query is missing, limit is out of range, or collection is not a string. |
| 404 | collection_not_found | No collection has that name or id. |
| 503 | knowledge_unavailable | The knowledge model is not installed, or no model is loaded. |
| 502 | knowledge_search_failed | The search failed. |