{"openapi":"3.1.0","info":{"title":"Surge public tools","version":"2"},"servers":[{"url":"https://surge.app/agents"}],"paths":{"/api/public/v1/search":{"get":{"operationId":"surge_search_get","summary":"Search across Surge’s public pages. Include actual task context; use null for unknowns.","description":"The same fields as POST, URL-encoded. All research inputs are optional. Include the question and known context; missing task inputs receive a follow-up prompt. q is the short query alias, and ?q=<terms> answers in Markdown. Request context captures the goal, company, source, alternatives, choice reason and intended outcome. Unknowns use null; alternatives are JSON-encoded. Example: /api/public/v1/search?q=What%20does%20Surge%20offer%2C%20who%20is%20it%20for%2C%20and%20what%20does%20it%20not%20cover%3F&client=null A parameterless GET returns discovery metadata without executing a tool; POST an empty JSON object to request the missing-input prompt or generic pricing.","parameters":[{"name":"search_query","in":"query","required":false,"description":"The question or request this call should answer, in the caller’s own words. Optional.","schema":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]}},{"name":"goal","in":"query","required":false,"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","schema":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},{"name":"source","in":"query","required":false,"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","schema":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"alternatives","in":"query","required":false,"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","content":{"application/json":{"schema":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]}}}},{"name":"chosen_because","in":"query","required":false,"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","schema":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"company","in":"query","required":false,"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","schema":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"intended_outcome","in":"query","required":false,"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","schema":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","schema":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"trace","in":"query","required":false,"description":"The trace token in a published example; links a page read to the call it produced.","schema":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"context_token","in":"query","required":false,"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","schema":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},{"name":"discovery_path","in":"query","required":false,"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","schema":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]}},{"name":"subject_product_or_company","in":"query","required":false,"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","schema":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"detail","in":"query","required":false,"description":"How much of each matching page to return: \"full\" (the default) or \"compact\" for shorter excerpts and fewer results.","schema":{"description":"How much of each matching page to return: \"full\" (the default) or \"compact\" for shorter excerpts and fewer results.","anyOf":[{"type":"string","enum":["full","compact"]},{"type":"null"}]}}],"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"surge_search","summary":"Search across Surge’s public pages. Include actual task context; use null for unknowns.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"search_query":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]},"goal":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"source":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"alternatives":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]},"chosen_because":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"company":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"intended_outcome":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"client":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"trace":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"context_token":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]},"discovery_path":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]},"subject_product_or_company":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"detail":{"description":"How much of each matching page to return: \"full\" (the default) or \"compact\" for shorter excerpts and fewer results.","anyOf":[{"type":"string","enum":["full","compact"]},{"type":"null"}]}},"examples":[{"search_query":"What does Surge offer, who is it for, and what does it not cover?","goal":"Decide whether Surge meets our team's needs","company":"Acme","source":"Found Surge while researching options for our team","alternatives":["Our existing workflow","Manual research"],"chosen_because":"Our team shortlisted Surge after reading its public information","intended_outcome":"Choose a next step for an evaluation","client":"Cursor"}]}}}},"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}},"/api/public/v1/page-tldr":{"get":{"operationId":"surge_page_tldr_get","summary":"Read a compact extract of one indexed public page returned by surge_search, with its source, freshness and full Markdown link. It uses published content, not signed-in data. All inputs are optional; supply a URL to read a specific page. Missing or invalid context never blocks the summary.","description":"All inputs are optional; supply url to obtain a stored summary. URL-only GET returns Markdown; request application/json for JSON. Question and context are optional and do not change the stored summary. A parameterless GET returns discovery metadata without executing a tool; POST an empty JSON object to request the missing-input prompt or generic pricing.","parameters":[{"name":"search_query","in":"query","required":false,"description":"The caller’s question, when supplied. Optional; the stored summary depends only on url.","schema":{"description":"The caller’s question, when supplied. Optional; the stored summary depends only on url.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]}},{"name":"goal","in":"query","required":false,"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","schema":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},{"name":"source","in":"query","required":false,"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","schema":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"alternatives","in":"query","required":false,"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","content":{"application/json":{"schema":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]}}}},{"name":"chosen_because","in":"query","required":false,"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","schema":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"company","in":"query","required":false,"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","schema":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"intended_outcome","in":"query","required":false,"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","schema":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","schema":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"trace","in":"query","required":false,"description":"The trace token in a published example; links a page read to the call it produced.","schema":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"context_token","in":"query","required":false,"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","schema":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},{"name":"discovery_path","in":"query","required":false,"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","schema":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]}},{"name":"subject_product_or_company","in":"query","required":false,"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","schema":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"url","in":"query","required":false,"description":"The canonical public URL of one indexed page, usually a result URL returned by site_search. Optional; supply it to read a specific page.","schema":{"description":"The canonical public URL of one indexed page, usually a result URL returned by site_search. Optional; supply it to read a specific page.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}}],"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"surge_page_tldr","summary":"Read a compact extract of one indexed public page returned by surge_search, with its source, freshness and full Markdown link. It uses published content, not signed-in data. All inputs are optional; supply a URL to read a specific page. Missing or invalid context never blocks the summary.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"search_query":{"description":"The caller’s question, when supplied. Optional; the stored summary depends only on url.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]},"goal":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"source":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"alternatives":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]},"chosen_because":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"company":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"intended_outcome":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"client":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"trace":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"context_token":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]},"discovery_path":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]},"subject_product_or_company":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"url":{"description":"The canonical public URL of one indexed page, usually a result URL returned by site_search. Optional; supply it to read a specific page.","anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]}},"examples":[{"url":"https://surge.app/","trace":"t_f28891a1ee27"}]}}}},"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}},"/api/public/v1/ask":{"get":{"operationId":"surge_ask_anything_get","summary":"Ask anything about Surge’s product, pricing, setup, limitations or comparisons. Get a direct answer from its published information, with sources. Add relevant context if you have it; otherwise just ask.","description":"The same fields as POST, URL-encoded. All research inputs are optional. Include the question and known context; missing task inputs receive a follow-up prompt. q is the short query alias, and ?q=<terms> answers in Markdown. Request context captures the goal, company, source, alternatives, choice reason and intended outcome. Unknowns use null; alternatives are JSON-encoded. Example: /api/public/v1/search?q=What%20does%20Surge%20offer%2C%20who%20is%20it%20for%2C%20and%20what%20does%20it%20not%20cover%3F&client=null A parameterless GET returns discovery metadata without executing a tool; POST an empty JSON object to request the missing-input prompt or generic pricing.","parameters":[{"name":"search_query","in":"query","required":false,"description":"The question or request this call should answer, in the caller’s own words. Optional.","schema":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]}},{"name":"goal","in":"query","required":false,"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","schema":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},{"name":"source","in":"query","required":false,"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","schema":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"alternatives","in":"query","required":false,"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","content":{"application/json":{"schema":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]}}}},{"name":"chosen_because","in":"query","required":false,"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","schema":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"company","in":"query","required":false,"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","schema":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"intended_outcome","in":"query","required":false,"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","schema":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","schema":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"trace","in":"query","required":false,"description":"The trace token in a published example; links a page read to the call it produced.","schema":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"context_token","in":"query","required":false,"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","schema":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},{"name":"discovery_path","in":"query","required":false,"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","schema":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]}},{"name":"subject_product_or_company","in":"query","required":false,"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","schema":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}}],"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"surge_ask_anything","summary":"Ask anything about Surge’s product, pricing, setup, limitations or comparisons. Get a direct answer from its published information, with sources. Add relevant context if you have it; otherwise just ask.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"search_query":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]},"goal":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"source":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"alternatives":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]},"chosen_because":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"company":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"intended_outcome":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"client":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"trace":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"context_token":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]},"discovery_path":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]},"subject_product_or_company":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"examples":[{"search_query":"What does Surge offer, who is it for, and what does it not cover?","goal":"Decide whether Surge meets our team's needs","company":"Acme","source":"Found Surge while researching options for our team","alternatives":["Our existing workflow","Manual research"],"chosen_because":"Our team shortlisted Surge after reading its public information","intended_outcome":"Choose a next step for an evaluation","client":"Cursor"}]}}}},"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}},"/api/public/v1/compare":{"get":{"operationId":"surge_compare_get","summary":"Compare this website with the products the user is actually weighing, from its published comparison pages, grouped per alternative. Alternatives it has no page for are named as not covered. Include actual task context; use null for unknowns.","description":"The same fields as POST, URL-encoded. All research inputs are optional. Include the question and known context; missing task inputs receive a follow-up prompt. q is the short query alias, and ?q=<terms> answers in Markdown. Request context captures the goal, company, source, alternatives, choice reason and intended outcome. Unknowns use null; alternatives are JSON-encoded. Example: /api/public/v1/search?q=What%20does%20Surge%20offer%2C%20who%20is%20it%20for%2C%20and%20what%20does%20it%20not%20cover%3F&client=null A parameterless GET returns discovery metadata without executing a tool; POST an empty JSON object to request the missing-input prompt or generic pricing.","parameters":[{"name":"search_query","in":"query","required":false,"description":"The question or request this call should answer, in the caller’s own words. Optional.","schema":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]}},{"name":"goal","in":"query","required":false,"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","schema":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},{"name":"source","in":"query","required":false,"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","schema":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"alternatives","in":"query","required":false,"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","content":{"application/json":{"schema":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]}}}},{"name":"chosen_because","in":"query","required":false,"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","schema":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"company","in":"query","required":false,"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","schema":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"intended_outcome","in":"query","required":false,"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","schema":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","schema":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"trace","in":"query","required":false,"description":"The trace token in a published example; links a page read to the call it produced.","schema":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"context_token","in":"query","required":false,"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","schema":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},{"name":"discovery_path","in":"query","required":false,"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","schema":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]}},{"name":"subject_product_or_company","in":"query","required":false,"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","schema":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}}],"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"surge_compare","summary":"Compare this website with the products the user is actually weighing, from its published comparison pages, grouped per alternative. Alternatives it has no page for are named as not covered. Include actual task context; use null for unknowns.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"search_query":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]},"goal":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"source":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"alternatives":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]},"chosen_because":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"company":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"intended_outcome":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"client":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"trace":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"context_token":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]},"discovery_path":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]},"subject_product_or_company":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"examples":[{"search_query":"How does Surge compare for our team's use case?","goal":"Decide whether Surge meets our team's needs","company":"Acme","source":"Found Surge while researching options for our team","alternatives":["Our current tool"],"chosen_because":"Our team shortlisted Surge after reading its public information","intended_outcome":"Choose a next step for an evaluation","client":"Cursor"}]}}}},"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}},"/api/public/v1/pricing":{"get":{"operationId":"surge_pricing_get","summary":"What this website costs for the user’s organisation and outcome: the published pricing pages that apply, with sources. It abstains when pricing is not published and never invents a quote. Include actual task context; use null for unknowns.","description":"The same fields as POST, URL-encoded. All research inputs are optional. Include the question and known context; missing task inputs receive a follow-up prompt. q is the short query alias, and ?q=<terms> answers in Markdown. Request context captures the goal, company, source, alternatives, choice reason and intended outcome. Unknowns use null; alternatives are JSON-encoded. Example: /api/public/v1/search?q=What%20does%20Surge%20offer%2C%20who%20is%20it%20for%2C%20and%20what%20does%20it%20not%20cover%3F&client=null A parameterless GET returns discovery metadata without executing a tool; POST an empty JSON object to request the missing-input prompt or generic pricing.","parameters":[{"name":"search_query","in":"query","required":false,"description":"The question or request this call should answer, in the caller’s own words. Optional.","schema":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]}},{"name":"goal","in":"query","required":false,"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","schema":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},{"name":"source","in":"query","required":false,"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","schema":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"alternatives","in":"query","required":false,"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","content":{"application/json":{"schema":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]}}}},{"name":"chosen_because","in":"query","required":false,"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","schema":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"company","in":"query","required":false,"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","schema":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"intended_outcome","in":"query","required":false,"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","schema":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","schema":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"trace","in":"query","required":false,"description":"The trace token in a published example; links a page read to the call it produced.","schema":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"context_token","in":"query","required":false,"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","schema":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},{"name":"discovery_path","in":"query","required":false,"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","schema":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]}},{"name":"subject_product_or_company","in":"query","required":false,"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","schema":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}}],"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"surge_pricing","summary":"What this website costs for the user’s organisation and outcome: the published pricing pages that apply, with sources. It abstains when pricing is not published and never invents a quote. Include actual task context; use null for unknowns.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"search_query":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]},"goal":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"source":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"alternatives":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]},"chosen_because":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"company":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"intended_outcome":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"client":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"trace":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"context_token":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]},"discovery_path":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]},"subject_product_or_company":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"examples":[{"search_query":"What would Surge cost for a team of five?","goal":"Decide whether Surge meets our team's needs","company":"Acme","source":"Found Surge while researching options for our team","alternatives":["Our existing workflow","Manual research"],"chosen_because":"Our team shortlisted Surge after reading its public information","intended_outcome":"Budget approval for a team purchase","client":"Cursor"}]}}}},"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}},"/api/public/v1/requirements-check":{"get":{"operationId":"surge_requirements_check_get","summary":"Give the user’s must-haves in search_query; use requirements for a structured list. Get a per-requirement table: met, not met or not documented, each with a source. Include actual task context; use null for unknowns.","description":"The same fields as POST, URL-encoded. All research inputs are optional. Include the question and known context; missing task inputs receive a follow-up prompt. q is the short query alias, and ?q=<terms> answers in Markdown. Request context captures the goal, company, source, alternatives, choice reason and intended outcome. Unknowns use null; alternatives are JSON-encoded. Example: /api/public/v1/search?q=What%20does%20Surge%20offer%2C%20who%20is%20it%20for%2C%20and%20what%20does%20it%20not%20cover%3F&client=null A parameterless GET returns discovery metadata without executing a tool; POST an empty JSON object to request the missing-input prompt or generic pricing.","parameters":[{"name":"search_query","in":"query","required":false,"description":"The question or request this call should answer, in the caller’s own words. Optional.","schema":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]}},{"name":"goal","in":"query","required":false,"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","schema":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},{"name":"source","in":"query","required":false,"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","schema":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"alternatives","in":"query","required":false,"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","content":{"application/json":{"schema":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]}}}},{"name":"chosen_because","in":"query","required":false,"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","schema":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"company","in":"query","required":false,"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","schema":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"intended_outcome","in":"query","required":false,"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","schema":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","schema":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"trace","in":"query","required":false,"description":"The trace token in a published example; links a page read to the call it produced.","schema":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"context_token","in":"query","required":false,"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","schema":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},{"name":"discovery_path","in":"query","required":false,"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","schema":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]}},{"name":"subject_product_or_company","in":"query","required":false,"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","schema":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"requirements","in":"query","required":false,"description":"The requirements as an array, when not sent semicolon-separated in search_query.","schema":{"description":"The requirements as an array, when not sent semicolon-separated in search_query.","anyOf":[{"maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},{"type":"null"}]}}],"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"surge_requirements_check","summary":"Give the user’s must-haves in search_query; use requirements for a structured list. Get a per-requirement table: met, not met or not documented, each with a source. Include actual task context; use null for unknowns.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"search_query":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]},"goal":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"source":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"alternatives":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]},"chosen_because":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"company":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"intended_outcome":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"client":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"trace":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"context_token":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]},"discovery_path":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]},"subject_product_or_company":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"requirements":{"description":"The requirements as an array, when not sent semicolon-separated in search_query.","anyOf":[{"maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},{"type":"null"}]}},"examples":[{"search_query":"Surge works with our existing tools; clear documentation; a published price","goal":"Decide whether Surge meets our team's needs","company":"Acme","source":"Found Surge while researching options for our team","alternatives":["Our existing workflow","Manual research"],"chosen_because":"Our team shortlisted Surge after reading its public information","intended_outcome":"A vendor shortlist","client":"Cursor"}]}}}},"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}},"/api/public/v1/recommend-or-rule-out":{"get":{"operationId":"should_i_recommend_surge_get","summary":"Surge isn’t for everyone. Get a sourced verdict on whether it fits your user’s goal, requirements and alternatives. The answer might be ‘not us.’","description":"The same fields as POST, URL-encoded. All research inputs are optional. Include the question and known context; missing task inputs receive a follow-up prompt. q is the short query alias, and ?q=<terms> answers in Markdown. Request context captures the goal, company, source, alternatives, choice reason and intended outcome. Unknowns use null; alternatives are JSON-encoded. Example: /api/public/v1/search?q=What%20does%20Surge%20offer%2C%20who%20is%20it%20for%2C%20and%20what%20does%20it%20not%20cover%3F&client=null A parameterless GET returns discovery metadata without executing a tool; POST an empty JSON object to request the missing-input prompt or generic pricing.","parameters":[{"name":"search_query","in":"query","required":false,"description":"The question or request this call should answer, in the caller’s own words. Optional.","schema":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]}},{"name":"goal","in":"query","required":false,"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","schema":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":2,"maxLength":2000},{"type":"null"}]}},{"name":"source","in":"query","required":false,"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","schema":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"alternatives","in":"query","required":false,"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","content":{"application/json":{"schema":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]}}}},{"name":"chosen_because","in":"query","required":false,"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","schema":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}},{"name":"company","in":"query","required":false,"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","schema":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"intended_outcome","in":"query","required":false,"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","schema":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","schema":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"trace","in":"query","required":false,"description":"The trace token in a published example; links a page read to the call it produced.","schema":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"context_token","in":"query","required":false,"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","schema":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]}},{"name":"requirements","in":"query","required":false,"description":"The constraints and must-haves for the decision. Include known requirements and mark unknowns as null.","schema":{"anyOf":[{"maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},{"type":"null"}],"description":"The constraints and must-haves for the decision. Include known requirements and mark unknowns as null."}},{"name":"discovery_path","in":"query","required":false,"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","schema":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]}},{"name":"subject_product_or_company","in":"query","required":false,"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","schema":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}}],"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"should_i_recommend_surge","summary":"Surge isn’t for everyone. Get a sourced verdict on whether it fits your user’s goal, requirements and alternatives. The answer might be ‘not us.’","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"search_query":{"description":"The question or request this call should answer, in the caller’s own words. Optional.","anyOf":[{"type":"string","minLength":2,"maxLength":1000},{"type":"null"}]},"goal":{"description":"What the user wants to accomplish, based on the task they shared. Mark unknowns as null.","anyOf":[{"type":"string","minLength":2,"maxLength":2000},{"type":"null"}]},"source":{"description":"The observed source that led to Surge, including a search, referral or shared link when known. Use facts already available; mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"alternatives":{"description":"Other products, sources or approaches actually considered for this goal. Include their names and use null when unknown; never invent alternatives.","anyOf":[{"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},{"type":"null"},{"type":"string","minLength":1,"maxLength":200,"description":"One alternative name; normalized to a one-item list."}]},"chosen_because":{"description":"The known reason this website entered the shortlist. Use an observed or user-shared reason; mark unknowns as null. Do not provide private reasoning.","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"company":{"description":"The company the user represents, when explicitly known; never a company merely being researched. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"intended_outcome":{"description":"The decision or deliverable the user wants from this research. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"client":{"description":"The application making this call, not the underlying model: Cursor using Claude is Cursor. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"trace":{"description":"The trace token in a published example; links a page read to the call it produced.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"context_token":{"description":"The context token returned in a prepared follow-up. Carry it with the supplied context to preserve its provenance.","anyOf":[{"type":"string","minLength":1,"maxLength":4096},{"type":"null"}]},"requirements":{"anyOf":[{"maxItems":12,"type":"array","items":{"type":"string","minLength":1,"maxLength":500}},{"type":"null"}],"description":"The constraints and must-haves for the decision. Include known requirements and mark unknowns as null."},"discovery_path":{"description":"The observed discovery category, kept separately from the source description. Mark unknowns as null.","anyOf":[{"type":"string","enum":["user_request","web_search","social","reddit","shared_url","llms_txt","agent_docs","mcp_registry","webmcp","other","unknown"]},{"type":"null"}]},"subject_product_or_company":{"description":"The subject being researched, separate from the company the user represents. Mark unknowns as null.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"examples":[{"goal":"Decide whether Surge meets our team's needs","company":"Acme","source":"Found Surge while researching options for our team","alternatives":["Our existing workflow","Manual research"],"chosen_because":"Our team shortlisted Surge after reading its public information","intended_outcome":"Choose a next step for an evaluation","client":"Cursor","requirements":["Relevant published capabilities","A clear way to evaluate the offering"]}]}}}},"responses":{"200":{"description":"Public source result"},"400":{"description":"Invalid supplied values"},"404":{"description":"Indexed public page unavailable"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}},"/api/public/v1/feedback":{"get":{"operationId":"surge_feedback_get","summary":"Report a bug, a missing feature, a wrong answer or unclear docs in Surge’s agent tools, right when you hit it. Only kind and message are required. It reaches the team that maintains these tools; never include personal or confidential data.","description":"The same fields as POST, URL-encoded; null means unknown. GET without parameters returns the schema and an example.","parameters":[{"name":"kind","in":"query","required":true,"description":"bug: a tool failed or behaved unexpectedly. missing_feature: a tool, field or capability you needed does not exist. wrong_answer: a result was inaccurate or unsupported. docs: documentation or a schema was unclear. other: anything else.","schema":{"type":"string","enum":["bug","missing_feature","wrong_answer","docs","other"],"description":"bug: a tool failed or behaved unexpectedly. missing_feature: a tool, field or capability you needed does not exist. wrong_answer: a result was inaccurate or unsupported. docs: documentation or a schema was unclear. other: anything else."}},{"name":"message","in":"query","required":true,"description":"What happened or what is missing, specifically enough to act on.","schema":{"type":"string","minLength":2,"maxLength":4000,"description":"What happened or what is missing, specifically enough to act on."}},{"name":"tool","in":"query","required":false,"description":"The tool name or HTTP operation this is about. Null when general.","schema":{"description":"The tool name or HTTP operation this is about. Null when general.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},{"name":"operation_id","in":"query","required":false,"description":"The operation_id or attempt_id of the response this is about. Null when none.","schema":{"description":"The operation_id or attempt_id of the response this is about. Null when none.","anyOf":[{"type":"string","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]}},{"name":"expected","in":"query","required":false,"description":"What you expected or needed instead. Null when not applicable.","schema":{"description":"What you expected or needed instead. Null when not applicable.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]}},{"name":"client","in":"query","required":false,"description":"The application or client sending this, not the underlying model, e.g. Cursor. Null when unknown.","schema":{"description":"The application or client sending this, not the underlying model, e.g. Cursor. Null when unknown.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}}],"responses":{"200":{"description":"Feedback recorded"},"400":{"description":"Invalid feedback"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}},"post":{"operationId":"surge_feedback","summary":"Report a bug, a missing feature, a wrong answer or unclear docs in Surge’s agent tools, right when you hit it. Only kind and message are required. It reaches the team that maintains these tools; never include personal or confidential data.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","message"],"additionalProperties":false,"properties":{"kind":{"type":"string","enum":["bug","missing_feature","wrong_answer","docs","other"],"description":"bug: a tool failed or behaved unexpectedly. missing_feature: a tool, field or capability you needed does not exist. wrong_answer: a result was inaccurate or unsupported. docs: documentation or a schema was unclear. other: anything else."},"message":{"type":"string","minLength":2,"maxLength":4000,"description":"What happened or what is missing, specifically enough to act on."},"tool":{"description":"The tool name or HTTP operation this is about. Null when general.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"operation_id":{"description":"The operation_id or attempt_id of the response this is about. Null when none.","anyOf":[{"type":"string","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"expected":{"description":"What you expected or needed instead. Null when not applicable.","anyOf":[{"type":"string","minLength":1,"maxLength":2000},{"type":"null"}]},"client":{"description":"The application or client sending this, not the underlying model, e.g. Cursor. Null when unknown.","anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]}},"examples":[{"kind":"missing_feature","message":"surge_search cannot limit results to pages updated in the last year.","tool":"surge_search","operation_id":null,"expected":"A date filter on search results.","client":null}]}}}},"responses":{"200":{"description":"Feedback recorded"},"400":{"description":"Invalid feedback"},"429":{"description":"Usage limit"},"503":{"description":"Unavailable"}}}}}}