Skip to main content

Knowledge Source Endpoint Contract

The Knowledge Source (“lens”) protocol is shared between the getbased app’s in-chat Custom Knowledge Source and the getbased-mcp server — one server speaking this contract backs both. User-facing setup lives in the Interpretive Lens guide; this page is the wire spec for rolling your own server.

Endpoint contract

If you’re setting up your own knowledge source server, it must implement a single POST route returning relevant passages. Request:
Response (200):
Error response (non-200):
Constraints:
  • HTTPS required for public hosts. Plain http:// is accepted for hosts that can’t leak your Bearer token over the public internet: loopback (localhost, 127.0.0.1, [::1]), RFC1918 LAN (10.x, 172.16–31.x, 192.168.x), link-local (169.254.x), Tailscale CGNAT (100.64–127.x), and mDNS (*.local). Anything else must be https://.
  • Max response size: 32 KB (larger responses are rejected)
  • Max passages: 10 (client truncates)
  • CORS: your server must send Access-Control-Allow-Origin: * (or the getbased origin)
  • Timeout: 30 seconds — slower responses fall back to unenriched AI
  • No redirects: 3xx responses are rejected (prevents Bearer header leaking)

Example server (FastAPI)

Example server (Express)

Caching

getbased caches each query for 5 minutes (up to 20 entries, scoped per profile). Switching profiles, changing the config, or clicking Clear cache in settings flushes the cache.