{"openapi":"3.1.0","info":{"title":"aisearch","version":"1.0.0","summary":"Cited AI web search: raw results plus a synthesised, verifiably-cited Markdown report.","description":"Web search for agents. Every endpoint returns Markdown with inline [n] citations plus a citations[] array. Citation markers are rendered from the search API's own source attribution rather than written by the model, so an invented citation is not possible. Paid per call over x402 (USDC on Base) — no account or API key. Bad input is rejected with 4xx and a failed model call returns 5xx; neither is charged.","x-pricing":{"currency":"USDC","network":"eip155:8453 (Base mainnet)","perCall":{"/answer":"$0.008","/search":"$0.02","/compare":"$0.03","/research":"$0.25"}}},"servers":[{"url":"https://aisearch.x.c00l.site"}],"paths":{"/":{"get":{"summary":"Landing page (free)","responses":{"200":{"description":"HTML documentation.","content":{"text/html":{}}}}}},"/health":{"get":{"summary":"Health check (free)","responses":{"200":{"description":"Service is up.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]},"example":{"ok":true}}}}}}},"/openapi.json":{"get":{"summary":"This document (free)","responses":{"200":{"description":"OpenAPI 3.1 document.","content":{"application/json":{}}}}}},"/answer":{"post":{"summary":"Fast cited factual answer ($0.008)","description":"Single-shot factual lookup. One short paragraph, citations, no report structure. Returns an explicit \"could not find a reliable source\" rather than guessing, and flags a false premise instead of answering it. Measured latency 3–6 s.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":1200,"description":"The question."},"recency":{"type":"string","enum":["day","week","month","year","any"],"default":"any","description":"Preferred age of sources. Applied as a strong instruction to the model, not as a hard index filter — the search tool exposes no date filter, so an older source may still be used and will be flagged as such in the prose."}},"required":["query"]},"example":{"query":"What is the current Node.js LTS version?"}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"answer":{"type":"string","description":"Markdown, one paragraph, with [n] markers."},"citations":{"type":"array","items":{"type":"object","description":"A source attribution produced by the search API, not by the model.","properties":{"n":{"type":"integer","description":"Matches the [n] marker in the Markdown."},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"quote":{"type":["string","null"],"description":"The source's own words, up to ~150 chars."},"quotes":{"type":"array","items":{"type":"string"},"description":"Every quote attributed to this source."}},"required":["n","url","title"]}},"sources":{"type":"array","items":{"type":"string","format":"uri"}},"grounded":{"type":"boolean","description":"false means no citation was produced — treat as unverified."},"searchQueries":{"type":"array","items":{"type":"string"}},"usage":{"type":"object","description":"Real token and tool counts for this call.","properties":{"inputTokens":{"type":"integer","description":"Uncached input tokens only."},"totalInputTokens":{"type":"integer","description":"inputTokens + cacheReadTokens + cacheWriteTokens — the real input volume."},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheWriteTokens":{"type":"integer"},"thinkingTokens":{"type":"integer"},"webSearches":{"type":"integer"},"webFetches":{"type":"integer"},"pagesRead":{"type":"integer"},"llmCalls":{"type":"integer"},"elapsedMs":{"type":"integer"}}},"model":{"type":"string"}},"required":["query","answer","citations","grounded","usage","model"]}}}},"400":{"description":"Invalid input. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"402":{"description":"Payment required — $0.008 per call. The PAYMENT-REQUIRED header carries the x402 challenge.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64 x402 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"Input too large. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"The model failed or returned unusable output. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"The model or the search backend is unavailable. Never charged. Retryable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"504":{"description":"The model exceeded the time budget. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/search":{"post":{"summary":"Cited web search with synthesised answer ($0.02)","description":"Searches the web and returns a cited Markdown answer, the citation list, the raw result set and follow-up questions. depth=standard also searches for evidence against the working answer. Measured latency ~5 s at depth=quick, 25–40 s at depth=standard.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":1200},"depth":{"type":"string","enum":["quick","standard"],"default":"standard"},"maxResults":{"type":"integer","minimum":1,"maximum":25,"default":10},"recency":{"type":"string","enum":["day","week","month","year","any"],"default":"any","description":"Preferred age of sources. Applied as a strong instruction to the model, not as a hard index filter — the search tool exposes no date filter, so an older source may still be used and will be flagged as such in the prose."},"includeRaw":{"type":"boolean","default":true,"description":"Set false to omit results[]."}},"required":["query"]},"example":{"query":"state of WebGPU browser support","depth":"standard","maxResults":10,"recency":"month"}}}},"responses":{"200":{"description":"Answer, citations and raw results.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"depth":{"type":"string"},"recency":{"type":"string"},"answer":{"type":"string","description":"Cited Markdown."},"citations":{"type":"array","items":{"type":"object","description":"A source attribution produced by the search API, not by the model.","properties":{"n":{"type":"integer","description":"Matches the [n] marker in the Markdown."},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"quote":{"type":["string","null"],"description":"The source's own words, up to ~150 chars."},"quotes":{"type":"array","items":{"type":"string"},"description":"Every quote attributed to this source."}},"required":["n","url","title"]}},"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"snippet":{"type":["string","null"],"description":"From the source attribution or the fallback backend. Never generated."},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Normalised where the backend gave a usable date."},"pageAge":{"type":["string","null"],"description":"Raw freshness string, e.g. \"3 hours ago\"."},"source":{"type":"string","enum":["web_search","citation","ecosia","wikipedia"]}},"required":["url","source"]}},"followUpQuestions":{"type":"array","items":{"type":"string"}},"searchQueries":{"type":"array","items":{"type":"string"},"description":"The queries actually issued."},"grounded":{"type":"boolean"},"truncated":{"type":"boolean"},"warnings":{"type":"array","description":"Non-fatal quality caveats. An empty array means none.","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"usage":{"type":"object","description":"Real token and tool counts for this call.","properties":{"inputTokens":{"type":"integer","description":"Uncached input tokens only."},"totalInputTokens":{"type":"integer","description":"inputTokens + cacheReadTokens + cacheWriteTokens — the real input volume."},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheWriteTokens":{"type":"integer"},"thinkingTokens":{"type":"integer"},"webSearches":{"type":"integer"},"webFetches":{"type":"integer"},"pagesRead":{"type":"integer"},"llmCalls":{"type":"integer"},"elapsedMs":{"type":"integer"}}},"model":{"type":"string"}},"required":["query","answer","citations","results","usage","model"]}}}},"400":{"description":"Invalid input. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"402":{"description":"Payment required — $0.02 per call. The PAYMENT-REQUIRED header carries the x402 challenge.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64 x402 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"Input too large. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"The model failed or returned unusable output. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"The model or the search backend is unavailable. Never charged. Retryable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"504":{"description":"The model exceeded the time budget. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/compare":{"post":{"summary":"Researched side-by-side comparison ($0.03)","description":"Researches each subject, then returns a verdict, a Markdown comparison table, the differences that would change a decision, caveats, and the same data as a structured JSON matrix with a per-cell verified flag. Unverifiable cells are reported as not found. Measured latency 55–80 s.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subjects":{"type":"array","minItems":2,"maxItems":6,"items":{"type":"string","maxLength":200}},"criteria":{"type":"array","maxItems":12,"items":{"type":"string","maxLength":160},"description":"Optional. Omit and the service picks decision-driving criteria."},"recency":{"type":"string","enum":["day","week","month","year","any"],"default":"any","description":"Preferred age of sources. Applied as a strong instruction to the model, not as a hard index filter — the search tool exposes no date filter, so an older source may still be used and will be flagged as such in the prose."}},"required":["subjects"]},"example":{"subjects":["Cloudflare Workers","AWS Lambda","Deno Deploy"],"criteria":["cold start","pricing model","runtime limits"]}}}},"responses":{"200":{"description":"Comparison and matrix.","content":{"application/json":{"schema":{"type":"object","properties":{"subjects":{"type":"array","items":{"type":"string"}},"criteria":{"type":["array","null"],"items":{"type":"string"}},"comparison":{"type":"string","description":"Cited Markdown: verdict, table, differences, caveats."},"matrix":{"type":["object","null"],"description":"Structured mirror of the table. null if it could not be produced (see warnings).","properties":{"subjects":{"type":"array","items":{"type":"string"}},"criteria":{"type":"array","items":{"type":"object","properties":{"criterion":{"type":"string"},"values":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"value":{"type":"string"},"verified":{"type":"boolean","description":"true only if a retrieved source supports the cell."}}}},"winner":{"type":["string","null"]},"note":{"type":["string","null"]}}}},"verdict":{"type":"string"},"overallWinner":{"type":["string","null"],"description":"null when the evidence supports no winner."}}},"citations":{"type":"array","items":{"type":"object","description":"A source attribution produced by the search API, not by the model.","properties":{"n":{"type":"integer","description":"Matches the [n] marker in the Markdown."},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"quote":{"type":["string","null"],"description":"The source's own words, up to ~150 chars."},"quotes":{"type":"array","items":{"type":"string"},"description":"Every quote attributed to this source."}},"required":["n","url","title"]}},"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"snippet":{"type":["string","null"],"description":"From the source attribution or the fallback backend. Never generated."},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Normalised where the backend gave a usable date."},"pageAge":{"type":["string","null"],"description":"Raw freshness string, e.g. \"3 hours ago\"."},"source":{"type":"string","enum":["web_search","citation","ecosia","wikipedia"]}},"required":["url","source"]}},"grounded":{"type":"boolean"},"warnings":{"type":"array","description":"Non-fatal quality caveats. An empty array means none.","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"usage":{"type":"object","description":"Real token and tool counts for this call.","properties":{"inputTokens":{"type":"integer","description":"Uncached input tokens only."},"totalInputTokens":{"type":"integer","description":"inputTokens + cacheReadTokens + cacheWriteTokens — the real input volume."},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheWriteTokens":{"type":"integer"},"thinkingTokens":{"type":"integer"},"webSearches":{"type":"integer"},"webFetches":{"type":"integer"},"pagesRead":{"type":"integer"},"llmCalls":{"type":"integer"},"elapsedMs":{"type":"integer"}}},"model":{"type":"string"}},"required":["subjects","comparison","citations","usage","model"]}}}},"400":{"description":"Invalid input. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"402":{"description":"Payment required — $0.03 per call. The PAYMENT-REQUIRED header carries the x402 challenge.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64 x402 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"Input too large. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"The model failed or returned unusable output. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"The model or the search backend is unavailable. Never charged. Retryable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"504":{"description":"The model exceeded the time budget. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}},"/research":{"post":{"summary":"Agentic deep research report ($0.25)","description":"Multi-step agentic investigation: plans sub-questions, searches each, opens and reads promising pages with a hardened SSRF-guarded reader, identifies its own gaps, searches for counter-evidence, then writes a structured report — executive summary, key findings, analysis, an evidence-quality table with a confidence rating, and what remains uncertain. Uses extended thinking. Hard caps on turns, page reads, subrequests and wall clock. WARNING: measured latency 205–254 s, worst case ~350 s. Set your client timeout to at least 360 s. Node's global fetch caps out at 300 s and will abort a legitimate call.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","maxLength":1200,"description":"The research question."},"focus":{"type":"string","maxLength":1200,"description":"Optional extra angle, constraint or audience."},"recency":{"type":"string","enum":["day","week","month","year","any"],"default":"any","description":"Preferred age of sources. Applied as a strong instruction to the model, not as a hard index filter — the search tool exposes no date filter, so an older source may still be used and will be flagged as such in the prose."},"maxTurns":{"type":"integer","minimum":2,"maximum":8,"default":8,"description":"Lower it to trade depth for latency."}},"required":["query"]},"example":{"query":"How production-ready is WebGPU in 2026, and what are the remaining blockers?","recency":"year"}}}},"responses":{"200":{"description":"The report.","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"focus":{"type":["string","null"]},"report":{"type":"string","description":"Long cited Markdown report."},"openQuestions":{"type":"array","items":{"type":"string"},"description":"Explicit remaining unknowns."},"citations":{"type":"array","items":{"type":"object","description":"A source attribution produced by the search API, not by the model.","properties":{"n":{"type":"integer","description":"Matches the [n] marker in the Markdown."},"url":{"type":"string","format":"uri"},"title":{"type":"string"},"quote":{"type":["string","null"],"description":"The source's own words, up to ~150 chars."},"quotes":{"type":"array","items":{"type":"string"},"description":"Every quote attributed to this source."}},"required":["n","url","title"]}},"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"snippet":{"type":["string","null"],"description":"From the source attribution or the fallback backend. Never generated."},"publishedAt":{"type":["string","null"],"format":"date-time","description":"Normalised where the backend gave a usable date."},"pageAge":{"type":["string","null"],"description":"Raw freshness string, e.g. \"3 hours ago\"."},"source":{"type":"string","enum":["web_search","citation","ecosia","wikipedia"]}},"required":["url","source"]}},"searchQueries":{"type":"array","items":{"type":"string"}},"pagesRead":{"type":"array","description":"Every page the agent actually opened.","items":{"type":"object","properties":{"url":{"type":"string"},"ok":{"type":"boolean"},"title":{"type":["string","null"]},"publishedAt":{"type":["string","null"]},"words":{"type":["integer","null"]}}}},"trace":{"type":"array","description":"Per-turn audit trail of the investigation.","items":{"type":"object","properties":{"turn":{"type":"integer"},"stopReason":{"type":"string"},"searches":{"type":"integer"},"fetches":{"type":"integer"},"queries":{"type":"array","items":{"type":"string"}},"reads":{"type":"array","items":{"type":"string"}},"thinkingBlocks":{"type":"integer"}}}},"completion":{"type":"object","properties":{"declaredComplete":{"type":"boolean","description":"true if the agent judged the investigation finished, rather than hitting a cap."},"stoppedBecause":{"type":"string","enum":["model_finished","turn_cap","time_budget","subrequest_budget","turn_error"]},"turns":{"type":"integer"},"pageReads":{"type":"integer"},"llmCalls":{"type":"integer"},"subrequests":{"type":"integer"}}},"truncated":{"type":"boolean"},"warnings":{"type":"array","description":"Non-fatal quality caveats. An empty array means none.","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"usage":{"type":"object","description":"Real token and tool counts for this call.","properties":{"inputTokens":{"type":"integer","description":"Uncached input tokens only."},"totalInputTokens":{"type":"integer","description":"inputTokens + cacheReadTokens + cacheWriteTokens — the real input volume."},"outputTokens":{"type":"integer"},"cacheReadTokens":{"type":"integer"},"cacheWriteTokens":{"type":"integer"},"thinkingTokens":{"type":"integer"},"webSearches":{"type":"integer"},"webFetches":{"type":"integer"},"pagesRead":{"type":"integer"},"llmCalls":{"type":"integer"},"elapsedMs":{"type":"integer"}}},"model":{"type":"string"}},"required":["query","report","citations","usage","model"]}}}},"400":{"description":"Invalid input. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"402":{"description":"Payment required — $0.25 per call. The PAYMENT-REQUIRED header carries the x402 challenge.","headers":{"PAYMENT-REQUIRED":{"schema":{"type":"string"},"description":"Base64 x402 challenge."}},"content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"Input too large. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"502":{"description":"The model failed or returned unusable output. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"503":{"description":"The model or the search backend is unavailable. Never charged. Retryable.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}},"504":{"description":"The model exceeded the time budget. Never charged.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}}}}}}}}