API Reference · v0.1

KlawSearch Docs

One API call turns the web — and SEC filings — into clean, ranked, agent-ready JSON. Tavily-compatible response shape, so existing adapters drop in unchanged.

Quickstart

Install the SDK and make your first call in under a minute.

pip install klawsearch
export KLAWSEARCH_API_KEY=ks-live-...

from klawsearch import KlawSearch

client = KlawSearch()                       # reads KLAWSEARCH_API_KEY
r = client.search("AAPL 10-K risk factors", max_results=5)
print(r.answer)
for hit in r:
    print(hit.score, hit.url)

Prefer raw HTTP? Every endpoint is a plain JSON POST — see thecurl examples below.

Authentication

All requests require a bearer token — your API key, created on the dashboard. Keys are prefixed ks-live-.

Authorization: Bearer ks-live-...

Base URL: https://api.klawsearch.com (or http://localhost:8000 when self-hosting).

POST/search

Hybrid web search — BM25 + vector + RRF fusion, optional LLM-synthesized answer.

Request body

Field	Type	Default	Notes
`query`	string	—	1–500 chars, required
`max_results`	int	5	1–20
`search_depth`	string	basic	`basic` \| `advanced` (advanced adds LLM rerank)
`include_domains`	string[]	[]	allowlist
`exclude_domains`	string[]	[]	blocklist
`include_answer`	bool	true	synthesize a cited answer
`include_raw_content`	bool	false	attach full page text

curl -X POST https://api.klawsearch.com/search \
  -H "Authorization: Bearer ks-live-..." \
  -H "Content-Type: application/json" \
  -d '{"query":"hybrid retrieval with pgvector","max_results":5}'

Response

{
  "query": "hybrid retrieval with pgvector",
  "answer": "Hybrid retrieval unions BM25 and vector top-k, then...",
  "results": [
    { "title": "...", "url": "...", "content": "...", "score": 0.86,
      "raw_content": null }
  ],
  "response_time": 0.74
}

POST/search/filings

Finance vertical — search SEC EDGAR filings (10-K, 10-Q, 8-K, …) by ticker, form type, and date range.

Request body

Field	Type	Default	Notes
`query`	string	—	1–500 chars, required
`ticker`	string?	null	e.g. `AAPL`
`form_types`	string[]	[10-K, 10-Q]	filter by form
`since` / `until`	date?	null	`filing_date` bounds
`max_results`	int	5	1–20
`search_depth`	string	basic	`basic` \| `advanced`
`include_answer`	bool	true	synthesize a cited answer

curl -X POST https://api.klawsearch.com/search/filings \
  -H "Authorization: Bearer ks-live-..." \
  -H "Content-Type: application/json" \
  -d '{"query":"supply chain risk","ticker":"AAPL","form_types":["10-K"]}'

POST/extract

Fetch and clean one or more URLs into agent-ready markdown (trafilatura).

Field	Type	Notes
`urls`	string[]	1–20 URLs, required

curl -X POST https://api.klawsearch.com/extract \
  -H "Authorization: Bearer ks-live-..." \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://sec.gov/.../aapl-10k.htm"]}'

Python SDK

Sync + async clients, plus a LangChain adapter. Install locally today (PyPI later):

pip install ./client

from klawsearch.langchain_compat import KlawSearchResults

tool = KlawSearchResults(max_results=5, api_key="ks-live-...")
tool.invoke("AAPL 10-K risk factors")

MCP server

Expose KlawSearch as tools to Goose, Claude Desktop, or OpenClaw over the Model Context Protocol.

pip install ./mcp

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "klawsearch": {
      "command": "klawsearch-mcp",
      "env": {
        "KLAWSEARCH_API_KEY": "ks-live-...",
        "KLAWSEARCH_BASE_URL": "https://api.klawsearch.com"
      }
    }
  }
}

Tools exposed: klawsearch_search, klawsearch_extract.

Rate limits

60 requests per minute per key by default (higher on paid plans). Repeated identical /search queries are served from cache in ~5ms. Need more? Talk to us.