4got API documentation ====================== 4got exposes a JSON/MessagePack API for programmatic search. All API endpoints require authentication unless noted otherwise. ENDPOINTS --------- GET /api/v1/search?q=QUERY&category=web Native 4got search API. Returns merged, deduplicated results from all engines with cross-engine scoring. Parameters: q - search query (required) category - web, images, videos, news, music (default: web) page - page number (default: 1) t - time range: day, week, month, year (optional) context - research context name (lowercase, digits, hyphens, up to 32 chars). Results already shown in that context are hidden; results returned are recorded, so many related queries hand back only what is new. Adds context, hidden_seen, marked_seen to the response. show_seen - 1 to include already-seen results anyway mark_seen - 0 to read without recording Response fields: query, category, elapsed_ms, engines_used, engines_errored, results (array of {score, engines, items}) format=html (web-type categories) is Load more's: page N of the results page's own list, as the results page drew page 1, as rendered rows {html, page, total_pages, new_hashes}; seen= (row hashes, comma-separated) leaves those rows out. total_pages is the pages known so far: one more while the engines' own next page is still to ask, the exact count once none is left. POST /mcp 4got as an MCP server (Model Context Protocol, Streamable HTTP, JSON-RPC 2.0), for AI agents. Same authentication as the rest of the API. Methods: initialize, ping, tools/list, tools/call. Tools: search query, category, limit; context, show_seen, mark_seen as for /api/v1/search list_contexts your contexts and how much each has seen forget_context clear (keep the name) or delete a context Contexts are the same objects a person sees under Settings > Research contexts, and are purged by "delete my server data". Example: curl -X POST -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \ https://HOST/mcp -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"search","arguments":{"query":"kdl config language","context":"kdl"}}}' GET /api/v1/web?s=QUERY 4get-compatible web search. Uses the same response envelope as 4get's /api/v1/web endpoint for drop-in compatibility. GET /api/v1/images?s=QUERY 4get-compatible image search. GET /api/v1/videos?s=QUERY 4get-compatible video search. GET /api/v1/news?s=QUERY 4get-compatible news search. GET /api/v1/music?s=QUERY 4get-compatible music search. GET /api/v1/ac?q=QUERY Autocomplete suggestions from multiple backends. No authentication required. Returns a JSON array of suggestion strings. GET /ami4got Instance information (version, engine count, uptime, etc.). CORS enabled. No authentication required. Returns: status, server info, real_searches, bot_requests, api_enabled, version, instances list. GET /api/v1/cache?key=HASH POST /api/v1/cache Peer cache sharing endpoints. Requires peer_cache permission or Bearer peer_secret. POST /api/v1/proxy?service=SERVICE&... Service proxy endpoint. Friends proxy services for each other. Requires peer_cache permission or Bearer peer_secret. The instance must have allow-proxy configured for the service. Services: translation - text, target (lang code) deepl - text, target lingva - text, target nllb - text, target wolfram - query autocomplete - query Response: {"result": "...", "service": "...", "via": "hostname"} POST /api/v1/relay Run one web search for a friend. Only for a friend whose pubkey and "relay true" are in this server's peers.kdl. Body (JSON, signed): {"q", "safe", "region", "page", "to", "asked_at"} Headers: X-Peer-Secret, X-Peer-Identity (the asker's fingerprint), X-Result-Signature (ed25519 over the body, base64). asked_at must be within 5 minutes of this server's clock. Body over 16 KB: 413. "to" must be this server's fingerprint. 200, 429 and 503 carry X-4got-Relay-Left (searches left this hour). 429 + Retry-After past relay-per-hour; 503 + Retry-After when busy. Response: {"results": [{"title", "url", "snippet", "engine", ...}]} AUTHENTICATION -------------- Three methods, checked in order: 1. Bearer token (owner access): Authorization: Bearer 2. API key: X-API-Key: API keys are generated by the instance owner at /admin/users. Each key has specific permissions (api_access, no_pow, etc.). 3. Session cookie: A valid 4got_session cookie from passing the captcha or PoW challenge. TESTING FROM A SCRIPT --------------------- A script testing 4got should send X-4got-Test: 1 so its searches stay out of Trending and the public log views. A client that cannot set headers can add test=1 to the address instead; it counts only from a client with no session cookie and a User-Agent that does not start with "Mozilla/", so a browser opening such a link is normally not marked. Requests with the owner secret in a header count as tests unless they send X-4got-Test: 0. This is separate from opting out of logging: a test search is still logged for the owner, marked as a machine's. A test search is bare: no Jev classifier, no language model, no Wolfram, no browser sidecar. Name the extras you are testing: X-4got-Want: rerank,merge or want=rerank,merge in the address of a single request. The names: routing, universal, indicators, source, merge, crawl, rerank, pagedates, platform_go, dict_pick, page_profile, cache_judge, planner, prefetch, clarify, followups, research_after, deep, research, translation, morelike, engine_advice, captions, each_language, wolfram, sidecar and all (nothing left out). The response says what you got in X-4got-Bare, and lists names it did not know in X-4got-Want-Unknown. The owner secret alone does not make a search bare. GET /feed/search?q=QUERY&category=web Per-query Atom feed of search results. Subscribe in any RSS reader to get fresh results for a query on each poll. Requires authentication. Respects Cache-Control for poll interval. GET /api/openapi.yaml OpenAPI 3.0 YAML specification for all API endpoints. No authentication required. MESSAGEPACK ----------- To receive MessagePack instead of JSON, set the Accept header: Accept: application/msgpack All endpoints that return JSON also support MessagePack with the same field names. CSV --- To receive CSV instead of JSON from /api/v1/search, either set: Accept: text/csv or append ?format=csv to the query string. The CSV has headers: title, url, snippet, engine. RATE LIMITS ----------- The instance owner sets a per-day search limit (default: 200). API key users share this limit. Exceeding it returns HTTP 429. EXAMPLES -------- # Search with API key curl -H "X-API-Key: YOUR_KEY" "https://HOST/api/v1/search?q=hello" # A test search: kept out of the search log and Trending curl -H "X-API-Key: YOUR_KEY" -H "X-4got-Test: 1" \ "https://HOST/api/v1/search?q=hello" # A test search with the oracle router on, and nothing else paid curl -H "X-API-Key: YOUR_KEY" -H "X-4got-Test: 1" -H "X-4got-Want: routing" \ "https://HOST/api/v1/search?q=is+it+going+to+rain+in+berlin" # 4get-compatible search curl -H "X-API-Key: YOUR_KEY" "https://HOST/api/v1/web?s=hello" # Autocomplete (no auth needed) curl "https://HOST/api/v1/ac?q=hel" # MessagePack response curl -H "X-API-Key: YOUR_KEY" \ -H "Accept: application/msgpack" \ "https://HOST/api/v1/search?q=hello" # Time-filtered search curl -H "X-API-Key: YOUR_KEY" \ "https://HOST/api/v1/search?q=hello&t=week"