{"openapi":"3.1.0","info":{"title":"freesea","version":"1.0.0","description":"Free web search and page fetching for AI agents, funded by clearly labeled sponsored results. Organic results are never reordered for sponsors."},"servers":[{"url":"https://freesea.dev"}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"SearchRequest":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":400},"max_results":{"default":10,"type":"integer","minimum":1,"maximum":20},"include_domains":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"exclude_domains":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"freshness":{"type":"string","enum":["day","week","month","year"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"search_depth":{"default":"basic","type":"string","enum":["basic","advanced"]},"max_content_tokens":{"type":"integer","minimum":100,"maximum":32000},"country":{"type":"string","minLength":2,"maxLength":2}},"required":["query"]},"SearchResponse":{"type":"object","properties":{"request_id":{"type":"string"},"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["organic","sponsored"]},"position":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"title":{"type":"string"},"url":{"type":"string"},"domain":{"type":"string"},"content":{"type":"string"},"extra_snippets":{"type":"array","items":{"type":"string"}},"raw_content":{"type":"string"},"published_date":{"type":"string"},"favicon":{"type":"string"},"disclosure":{"type":"string"},"rec_id":{"type":"string"},"incentive":{"type":"object","properties":{"kind":{"type":"string","enum":["credit","code","trial"]},"code":{"type":"string"},"benefit":{"type":"string"}},"required":["kind","benefit"],"additionalProperties":false}},"required":["type","title","url","domain","content"],"additionalProperties":false}},"response_time_ms":{"type":"number"},"meta":{"type":"object","properties":{"sponsored_count":{"type":"number"},"result_count":{"type":"number"}},"required":["sponsored_count","result_count"],"additionalProperties":false}},"required":["request_id","query","results","response_time_ms","meta"],"additionalProperties":false},"FetchRequest":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"max_chars":{"default":50000,"type":"integer","minimum":500,"maximum":200000}},"required":["url"]},"FetchResponse":{"type":"object","properties":{"request_id":{"type":"string"},"url":{"type":"string"},"final_url":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"chars":{"type":"number"},"truncated":{"type":"boolean"},"response_time_ms":{"type":"number"},"meta":{"type":"object","properties":{"unwrapped":{"type":"boolean"},"click_path":{"anyOf":[{"type":"string","const":"agent_read"},{"type":"null"}]},"content_type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["unwrapped","click_path","content_type"],"additionalProperties":false}},"required":["request_id","url","final_url","title","content","chars","truncated","response_time_ms","meta"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"status":{"type":"number"},"message":{"type":"string"}},"required":["status","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false}}},"paths":{"/v1/search":{"post":{"operationId":"search","summary":"Search the web","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":400},"max_results":{"default":10,"type":"integer","minimum":1,"maximum":20},"include_domains":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"exclude_domains":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"freshness":{"type":"string","enum":["day","week","month","year"]},"start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"end_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"search_depth":{"default":"basic","type":"string","enum":["basic","advanced"]},"max_content_tokens":{"type":"integer","minimum":100,"maximum":32000},"country":{"type":"string","minLength":2,"maxLength":2}},"required":["query"]}}}},"responses":{"200":{"description":"Ranked results, sponsored entries first and labeled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream search provider failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Monthly free budget exhausted, or backend unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"searchByQuery","summary":"Search the web (query-string convenience form)","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"The search query"},{"name":"max_results","in":"query","required":false,"schema":{"type":"string"}},{"name":"search_depth","in":"query","required":false,"schema":{"type":"string"}},{"name":"freshness","in":"query","required":false,"schema":{"type":"string"}},{"name":"country","in":"query","required":false,"schema":{"type":"string"}},{"name":"start_date","in":"query","required":false,"schema":{"type":"string"}},{"name":"end_date","in":"query","required":false,"schema":{"type":"string"}},{"name":"include_domains","in":"query","required":false,"schema":{"type":"string"},"description":"Repeat the parameter or pass a comma-separated list"},{"name":"exclude_domains","in":"query","required":false,"schema":{"type":"string"},"description":"Repeat the parameter or pass a comma-separated list"}],"responses":{"200":{"description":"Ranked results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream search provider failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Monthly free budget exhausted, or backend unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/fetch":{"post":{"operationId":"fetchPage","summary":"Fetch one page and return its main content as markdown","description":"Static fetch only: no JavaScript rendering, no cache, no extraction escalation chain. 10s timeout, hard character cap. Private, loopback and link-local addresses are refused.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":1,"maxLength":2048},"max_chars":{"default":50000,"type":"integer","minimum":500,"maximum":200000}},"required":["url"]}}}},"responses":{"200":{"description":"Extracted markdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FetchResponse"}}}},"400":{"description":"Invalid URL or request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, malformed or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Refused: private, loopback or reserved address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Unsupported content type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; see Retry-After","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Upstream fetch failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Backend unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"Upstream fetch timed out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}