API Reference

The EchoKB API lets you search your knowledge bases and retrieve documents programmatically. All endpoints require authentication via API token.

Authentication

All API requests must include an API token in the Authorization header.

Token Authentication

Authorization: Token <your_api_token>

Create and manage tokens on the API Tokens page. Tokens are hashed on creation — store the token value when first displayed, as it cannot be retrieved later.

Search

Search across one or more knowledge bases using BM25 full-text search with Hebrew stemming.

GET /api/v1/search

Parameters

Parameter	Type	Required	Description
kb_ids	string	Yes	Comma-separated list of knowledge base UUIDs (max 10)
query	string	Yes	Search query (1–500 characters)
limit	integer	No	Number of results to return (1–50, default 10)

Response

{
  "success": true,
  "results": [
    {
      "doc_id": "uuid",
      "source_id": "uuid",
      "kb_id": "uuid",
      "title": "Document title",
      "content": "Document content...",
      "rank": 4.21,
      "headline": "...matched <b>term</b>...",
      "metadata": {},
      "source_metadata": {}
    }
  ],
  "count": 1,
  "query": "search terms",
  "kb_ids": ["uuid"]
}

Examples

curl

curl -H "Authorization: Token YOUR_TOKEN" \
  "https://echokb.com/api/v1/search?kb_ids=KB_ID&query=חוזה+שכירות&limit=5"

Python

import requests

resp = requests.get(
    "https://echokb.com/api/v1/search",
    headers={"Authorization": "Token YOUR_TOKEN"},
    params={"kb_ids": "KB_ID", "query": "חוזה שכירות", "limit": 5},
)
data = resp.json()
for result in data["results"]:
    print(result["title"], result["rank"])

JavaScript

const params = new URLSearchParams({
  kb_ids: "KB_ID",
  query: "חוזה שכירות",
  limit: "5",
});

const resp = await fetch(`https://echokb.com/api/v1/search?${params}`, {
  headers: { Authorization: "Token YOUR_TOKEN" },
});
const data = await resp.json();
console.log(data.results);

Get Document

Retrieve the full content of a document as markdown.

GET /api/v1/docs/:source_id

Parameter	Type	Required	Description
source_id	uuid	Yes	Source UUID (path parameter). Also accepts legacy doc UUID for backward compatibility.

Response

Returns the document body as text/markdown; charset=utf-8.

curl

curl -H "Authorization: Token YOUR_TOKEN" \
  "https://echokb.com/api/v1/docs/SOURCE_ID"

Get Document URL

Retrieve the source URL for a document.

GET /api/v1/docs/:source_id/url

Parameter	Type	Required	Description
source_id	uuid	Yes	Source UUID (path parameter). Also accepts legacy doc UUID for backward compatibility.

Response

{
  "success": true,
  "url": "https://example.com/document.pdf"
}

curl

curl -H "Authorization: Token YOUR_TOKEN" \
  "https://echokb.com/api/v1/docs/DOC_ID/url"

Errors

All errors return a consistent JSON response format.

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

Status	Code	Description
400	INVALID_REQUEST	Missing or invalid parameters
401	UNAUTHORIZED	Missing, expired, or invalid token
403	FORBIDDEN	Token valid but insufficient permissions
404	NOT_FOUND	Resource not found or not accessible
500	INTERNAL_ERROR	Unexpected server error

Search Syntax

Queries are processed through a Hebrew-aware stemmer before matching. You can pass natural Hebrew text — the stemmer handles normalization automatically.

Feature	Description	Example
Niqqud stripping	Diacritical marks are removed before matching	שָׁלוֹם → שלומ
Final letter canonicalization	Final forms (ך,ם,ן,ף,ץ) are normalized to standard forms	חוזים → חוזימ
Prefix stripping	Common prefixes (ו,ה,ב,ל,כ,מ,ש and two-char combos) are stripped to generate variants	והחוזה → חוזה, והחוזה
Plural suffix stripping	Plural suffixes (ים, ות) are stripped from long-enough tokens	חוזימ → חוז, חוזימ
Legal abbreviations	Court/case-type abbreviations are expanded to full forms	בגצ → בגצ OR בית_משפט_גבוה_לצדק
OR-joined BM25	All variants are joined with OR for maximum recall	token1 OR token2 OR token3