POST /api/v1/ext/kb/query

Search the ANFI Knowledge Base across active, verified facts using PostgreSQL full-text search.

Implementation Notes

• authentication: X-API-Key
• required scope: kb:read
• search mode today: BM25 only
• domain filter: exact match when provided
• hard cap: top_k is capped server-side at 20
• request cost: 1 cent on successful completion

Request

curl -X POST https://api.tanfi.ai/api/v1/ext/kb/query \
  -H "X-API-Key: bach_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SR 11-7 model risk management",
    "top_k": 10,
    "domain": "AIML"
  }'

Request Body

Field	Type	Required	Rules
query	string	Yes	3..500 chars
top_k	integer	No	minimum 1, capped to 20 server-side
domain	string or null	No	max length 50

Response

{
  "results": [
    {
      "fact_id": "KB-SR117-0042",
      "fact_text": "Model risk is the potential for adverse consequences from decisions based on incorrect or misused model outputs and reports.",
      "verbatim_quote": "Model risk is the potential for adverse consequences...",
      "page_number": 3,
      "source_document_code": "SR117",
      "source_title": "SR 11-7: Supervisory Guidance on Model Risk Management",
      "authority_level": 1,
      "relevance_score": 0.8234,
      "domain": "AIML"
    }
  ],
  "total": 1,
  "query": "SR 11-7 model risk management",
  "domain": "AIML",
  "latency_ms": 42
}

Result Fields

Field	Type	Notes
fact_id	string	Canonical fact ID
fact_text	string	Fact content
verbatim_quote	string	Source quote
page_number	integer	Source page
source_document_code	string or null	Source code such as SR117
source_title	string or null	Human-readable source title
authority_level	integer	Numeric authority ranking
relevance_score	number	BM25 score rounded to 4 decimals
domain	string	Domain label from the fact row

Errors

Status	Shape	Meaning
400	{"detail":"..."}	API key was sent in query parameters
401	{"detail":"..."}	Missing or invalid API key
403	{"detail":{"error":"insufficient_scope","required":"kb:read"}}	Missing scope or blocked IP
422	FastAPI validation payload	Malformed body
429	{"detail":{...}}	Rate limit or budget exhausted
500	{"detail":{"error":"internal_error","message":"Knowledge base query failed"}}	Search failure
503	{"detail":{"error":"service_unavailable"}}	DB pool unavailable

Example 429 Payload

{
  "detail": {
    "error": "rate_limit_exceeded",
    "type": "sustained",
    "retry_after": 24,
    "limit": 60,
    "window_seconds": 60
  }
}