{"openapi":"3.1.0","info":{"title":"SearXNG API","description":"Privacy-respecting meta search engine aggregating results from multiple search engines","version":"1.0","contact":{"name":"SearXNG","url":"https://docs.searxng.org"},"license":{"name":"AGPL-3.0","url":"https://github.com/searxng/searxng/blob/master/LICENSE.txt"}},"servers":[{"url":"https://search.haiven.site","description":"Production SearXNG instance (via Traefik)"},{"url":"http://searxng:8080","description":"Internal Docker network endpoint"}],"tags":[{"name":"Search","description":"Search operations"},{"name":"Configuration","description":"Instance configuration and metadata"},{"name":"Health","description":"Health checks and status"}],"paths":{"/search":{"get":{"tags":["Search"],"summary":"Execute search query","description":"Search across multiple aggregated search engines with optional category and engine filtering","operationId":"search","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":500},"description":"Search query string","example":"artificial intelligence"},{"name":"categories","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated list of categories to search in","examples":["general","general,images,news","social media,files"]},"description":"Filter results by category (general, images, news, social media, files, map, music, videos, science, shopping, etc.)"},{"name":"engines","in":"query","required":false,"schema":{"type":"string","description":"Comma-separated list of specific engines to use","examples":["google,bing","duckduckgo"]},"description":"Restrict search to specific engines (google, bing, duckduckgo, brave, qwant, wikipedia, etc.)"},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","html","csv","rss"],"default":"json"},"description":"Response format"},{"name":"pageno","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination (1-indexed)"},{"name":"image_proxy","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Proxy image requests through SearXNG"},{"name":"time_range","in":"query","required":false,"schema":{"type":"string","enum":["day","week","month","year"]},"description":"Filter results by time range"},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"en-US"},"description":"Language code (ISO 639-1 with optional country code)","example":"en-US"},{"name":"safesearch","in":"query","required":false,"schema":{"type":"integer","enum":[0,1,2],"default":0},"description":"Safe search level: 0=off, 1=moderate, 2=strict"}],"responses":{"200":{"description":"Successful search","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","description":"Array of search results","items":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string","description":"Result title","example":"Artificial Intelligence - Wikipedia"},"url":{"type":"string","format":"uri","description":"Result URL","example":"https://en.wikipedia.org/wiki/Artificial_intelligence"},"content":{"type":"string","description":"Result snippet/content preview","example":"Artificial intelligence (AI) is intelligence demonstrated by machines..."},"engine":{"type":"string","description":"Search engine that provided this result","example":"google"},"category":{"type":"string","description":"Result category","example":"general"},"positions":{"type":"array","items":{"type":"integer"},"description":"Ranking positions from different engines","example":[1,2,3]},"score":{"type":"number","description":"Relevance score (0-1)","example":0.95},"pubdate":{"type":"string","format":"date-time","description":"Publication date (if available)","nullable":true},"img_src":{"type":"string","format":"uri","description":"Image URL (for image search results)","nullable":true},"thumbnail":{"type":"string","format":"uri","description":"Thumbnail image URL","nullable":true}}}},"corrected":{"type":"boolean","description":"Query was auto-corrected"},"correction":{"type":"string","description":"Corrected query if applicable","nullable":true},"number_of_results":{"type":"integer","description":"Total number of results found","example":1250000},"answers":{"type":"array","items":{"type":"object","properties":{"answer":{"type":"string"},"engine":{"type":"string"}}},"description":"Direct answers from engines (e.g., calculator results)"},"infoboxes":{"type":"array","items":{"type":"object"},"description":"Information boxes with structured data"},"suggestion":{"type":"array","items":{"type":"string"},"description":"Search suggestions for related queries"}}}}}},"400":{"description":"Bad request (missing or invalid query)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Missing required parameter: q"}}}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Search service temporarily unavailable"}}}}}}}}},"/config":{"get":{"tags":["Configuration"],"summary":"Get instance configuration","description":"Returns SearXNG instance configuration including enabled engines, categories, and settings","operationId":"getConfig","responses":{"200":{"description":"Instance configuration","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"object","description":"Available search categories","additionalProperties":{"type":"object","properties":{"engines":{"type":"array","items":{"type":"string"}},"name":{"type":"string"}}},"example":{"general":{"name":"General","engines":["google","bing","duckduckgo"]},"images":{"name":"Images","engines":["google images","bing images"]}}},"engines":{"type":"object","description":"Configured search engines","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"shortcut":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"},"language_support":{"type":"boolean"}}},"example":{"google":{"name":"Google","shortcut":"go","categories":["general","images"],"enabled":true}}},"language_support":{"type":"object","description":"Supported languages by code","additionalProperties":{"type":"string"},"example":{"en":"English","es":"Spanish","fr":"French"}},"plugins":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"enabled":{"type":"boolean"}}},"description":"Enabled plugins"},"autocomplete":{"type":"object","properties":{"backends":{"type":"array","items":{"type":"string"}}},"description":"Autocomplete configuration"}}}}}},"503":{"description":"Service unavailable"}}}},"/preferences":{"get":{"tags":["Configuration"],"summary":"Get preferences","description":"Get default user preferences","operationId":"getPreferences","responses":{"200":{"description":"User preferences","content":{"application/json":{"schema":{"type":"object","properties":{"language":{"type":"string","default":"en-US"},"theme":{"type":"string","enum":["light","dark"]},"image_proxy":{"type":"boolean"},"safesearch":{"type":"integer","enum":[0,1,2]},"results_on_new_tab":{"type":"boolean"}}}}}}}}},"/healthz":{"get":{"tags":["Health"],"summary":"Health check","description":"Check if SearXNG is operational and responsive","operationId":"health","responses":{"200":{"description":"Service is healthy","content":{"text/plain":{"schema":{"type":"string","example":"OK"}},"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","ok"]},"timestamp":{"type":"string","format":"date-time"}}}}}},"503":{"description":"Service is unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"unhealthy"},"error":{"type":"string"}}}}}}}}},"/stats":{"get":{"tags":["Health"],"summary":"Instance statistics","description":"Get statistics about search activity and engine status","operationId":"getStats","responses":{"200":{"description":"Statistics","content":{"application/json":{"schema":{"type":"object","properties":{"uptime":{"type":"number","description":"Uptime in seconds"},"requests":{"type":"object","properties":{"total":{"type":"integer"},"per_second":{"type":"number"}}},"engines":{"type":"object","description":"Per-engine statistics","additionalProperties":{"type":"object","properties":{"response_time":{"type":"number"},"load_time":{"type":"number"},"errors":{"type":"integer"},"success":{"type":"integer"}}}},"cache":{"type":"object","properties":{"size":{"type":"integer"},"hits":{"type":"integer"},"misses":{"type":"integer"}}}}}}}}}}}},"components":{"schemas":{"SearchResult":{"type":"object","required":["title","url"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"content":{"type":"string"},"engine":{"type":"string"},"category":{"type":"string"},"score":{"type":"number"},"pubdate":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string","nullable":true},"status":{"type":"integer"}}}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Optional API key for rate limit exceptions"}}},"security":[],"x-internal":{"docker_network":"backend","internal_port":8080,"external_domain":"search.haiven.site","traefik_enabled":true,"healthcheck_path":"/healthz","readiness_probe":{"path":"/search?q=test","timeout_seconds":5}}}