# x402serps > Pay-per-call web search (search results), news, and clean page extraction for AI agents. USDC on Base or Solana via x402. No account or API key. ## Endpoints (all POST JSON; unpaid requests return HTTP 402 with x402 payment requirements) - /api/v1/search $0.004 {"q":"...","num":10} (also GET ?q=&num=) -> {query,provider,results:[{position,title,url,snippet}]} - /api/v1/news $0.004 {"q":"...","num":10} -> {query,provider,results:[{position,title,url,snippet,source,date}]} - /api/v1/extract $0.003 {"url":"https://...","maxChars":50000} -> {url,finalUrl,title,contentType,markdown,length,truncated} - /api/v1/search-extract $0.02 {"q":"...","n":3} -> search results (top n, max 5) each with extracted markdown in "content" - /api/v1/batch $0.08 {"queries":["...", ...up to 25],"num":10} -> {count,results:[{query,provider,results}]} - /api/v1/images $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Image: image URL, thumbnail, size) - /api/v1/places $0.004 {"q":"...","num":10,"gl":"us","location":"London"} -> {query,provider,results:[...]} (Maps/places: address, rating, phone, website, lat/lng) - /api/v1/shopping $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Shopping: product, price, store, rating) - /api/v1/scholar $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Scholar: papers, year, citations, PDF) - /api/v1/videos $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Video: title, channel, duration, date) - /api/v1/answer $0.02 {"q":"...","n":4,"freshness":"week"} -> {query,answer,method,model,citations:[{id,title,url}]} (search + read top pages + cited answer; currently uses extractive summaries, i.e. quoted key sentences, not LLM prose) - /api/v1/crawl $0.002 per page {"url":"https://...","limit":10,"include":"/blog"} -> {url,count,pages:[{url,title,markdown}]} (same-host crawl, 1-50 pages, charged for limit) - /api/v1/map $0.002 {"url":"example.com","limit":200,"search":"docs"} -> {url,count,source,urls} (up to 1000 URLs from sitemaps + links) - Search/news filters: freshness (hour|day|week|month|year), dateFrom/dateTo (YYYY-MM-DD), raw tbs, page (pagination), num up to 100 (each 10 results = one $0.004 unit), gl, hl. - Multi-URL extract: {"urls":[... up to 20]} at $0.003 per URL (x402 v2 or credits). Research: "answer":true adds a cited answer (currently extractive summaries). - /api/v1/research $0.08 {"q":"...","n":5,"maxChars":20000} -> {query,method:"extractive",summary,keyPoints:[{text,source}],sources:[{id,title,url,excerpts}],related} (deep research: search + read top 3-8 pages, cited brief; ~5-20s) - /api/v1/visibility $0.10 flat {"brand":"example.com","keywords":["k1","... up to 10"],"gl":"us"} -> {domainTip (StableDomains: https://stabledomains.net),score 0-100,keywordsFound,topCompetitors,results:[{keyword,found,rank,url,features:{aiOverview,answerBox,peopleAlsoAsk,knowledgeGraph},competitors,score}]} (AI/SEO visibility) - /api/v1/competitor-report $0.30 {"domain":"example.com","keywords":["k1","... up to 8"],"gl":"us"} -> rankings per keyword, ads/advertisers, SERP features, share of voice, top competitors + their top pages, your top pages - /api/v1/leads $0.25 {"q":"dentists","location":"Leeds, UK","num":10} -> up to 20 Maps/places businesses enriched with business contact details only: role emails (info@, sales@, contact@), business phones and social links from their sites; personal-looking emails dropped; opt-outs (https://x402serps.com/opt-out) honoured; use subject to UK GDPR/PECR terms - /api/v1/seo-audit $0.20 {"domain":"example.com","brand":"Example","pages":8} -> indexed pages, title/meta/h1/canonical/noindex/alt checks, robots.txt, sitemap, brand rank, score 0-100, domainTip (find a name, then register it on StableDomains: https://stabledomains.net) - /api/v1/news-digest $0.05 {"topics":["t1","... up to 5"],"since":"day","num":10} -> deduplicated news per topic, top sources, text digest ## Monitors (credit key only) POST /api/v1/monitors with Authorization: Bearer xs_... and {"type":"rank","domain":"example.com","keywords":["k1",".. up to 10"],"gl":"us","webhook":"https://..."} (max(20, 10×keywords) credits/day) or {"type":"brand","query":"Example Inc","webhook":"https://..."} (30 credits/day). Runs immediately, then daily (06:00 UTC); first day charged at creation; pauses when credits run out. GET /api/v1/monitors lists, GET /api/v1/monitors/{id}?limit=7 returns results, PATCH {"active":true|false}, DELETE removes. Webhook gets POST JSON {monitor, result} per run. ## Integrations SDKs (packages coming soon; source and examples at https://x402serps.com/integrations) - JS class X402Serps, Python X402Serps. Tool schemas for OpenAI/Claude function calling: https://x402serps.com/tools.json Base URL: https://x402serps.com ## Prepaid credits (API key, pay by card) Prepaid credits (card via Stripe): $5 = 5,500 credits (1,375 searches), $20 = 24,000 credits (6,000 searches), $100 = 130,000 credits (32,500 searches). Buy at https://x402serps.com/pricing#credits; your API key (xs_...) is shown once after checkout. Send header Authorization: Bearer xs_... on any /api/v1 endpoint instead of paying with x402. 1 credit = $0.001: search/news/images/places/shopping/scholar/videos 4, extract 3 per URL, crawl 2 per page, map 2, answer 20, search-extract 20, batch 80, research 80, visibility 100, news-digest 50, seo-audit 200, leads 250, competitor-report 300. Response header X-Credits-Remaining. Balance: GET /api/v1/balance with the same header. Out of credits -> normal 402 (header X-Credits-Status). Unknown key -> 401. curl -X POST https://x402serps.com/api/v1/search -H "content-type: application/json" -H "Authorization: Bearer xs_YOUR_KEY" -d '{"q":"x402"}' ## Free MCP tier The MCP server (https://x402serps.com/api/mcp) gives 20 free web_search and extract calls a day per network (IPv4 /24), max 5 a minute, with no payment, key or signup. Just call the tool. web_search returns up to 10 results; extract takes one url. When the daily limit is reached the tool returns a message explaining how to pay: x402 per call (search $0.004, extract $0.003) or a prepaid credit key from https://x402serps.com/pricing?utm_campaign=100sales#credits. Resets 00:00 UTC. ## Free trial Free trial: send header X-Trial: 1 (no X-PAYMENT) to /api/v1/search, news, extract (and images, places, shopping, scholar, videos). research and visibility are paid-only (not in the trial). 25 free calls per network (IPv4 /24), max 10/minute; response header X-Trial-Remaining shows what's left. When used up, you get the normal 402 (header X-Trial-Status explains). Also works over MCP: send X-Trial: 1 on the MCP HTTP request. curl -X POST https://x402serps.com/api/v1/search -H "content-type: application/json" -H "X-Trial: 1" -d '{"q":"x402"}' ## MCP https://x402serps.com/api/mcp (streamable HTTP JSON). Tools: web_search {query,num} $0.004, news_search {query,num} $0.004, extract {url,maxChars} $0.003, search_extract {query,n,maxChars} $0.02, batch_search {queries[],num} $0.08, image_search {query,num,gl} $0.004, places_search {query,num,gl,location} $0.004, shopping_search {query,num,gl} $0.004, scholar_search {query,num,gl} $0.004, video_search {query,num,gl} $0.004, deep_research {query,n,maxChars} $0.08, ai_visibility_check {brand,keywords[],gl} $0.10. Send x402 payment in the X-PAYMENT header of the MCP HTTP request; without it, tools/call returns the payment requirements. initialize/tools/list are free. Manifest: https://x402serps.com/.well-known/mcp.json Setup (Claude Desktop, Cursor, generic): https://x402serps.com/mcp Cursor: {"mcpServers":{"x402serps":{"url":"https://x402serps.com/api/mcp"}}} Claude Desktop: {"mcpServers":{"x402serps":{"command":"npx","args":["-y","mcp-remote","https://x402serps.com/api/mcp"]}}} ## Discovery - OpenAPI: https://x402serps.com/openapi.json - x402: https://x402serps.com/.well-known/x402 ## Payment Solana: every paid endpoint also accepts USDC on Solana (asset EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, fee paid by facilitator). The 402 lists both options in accepts[]; your client picks one. scheme exact, network base, asset USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) (payTo is given in each 402 challenge). Failed requests (4xx/5xx) are not settled. Client: npm @x402/fetch + @x402/evm (Base) or @x402/svm (Solana), x402 v2. Legacy v1 x402-fetch 1.2.x still works with header X402-Version: 1. ## Quick start (JavaScript) import { wrapFetchWithPayment, x402Client } from "@x402/fetch"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; const f = wrapFetchWithPayment(fetch, new x402Client().register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.EVM_PRIVATE_KEY)))); // USDC on Base const r = await f("https://x402serps.com/api/v1/search",{method:"POST",headers:{"content-type":"application/json"},body:JSON.stringify({q:"x402"})}); ## Quick start (Python) from x402.clients.requests import x402_requests s = x402_requests(account); s.post("https://x402serps.com/api/v1/search", json={"q":"x402"}) ## Errors 400 bad input (not charged), 402 payment required/invalid, 502 upstream provider error (not charged). ## When to use which - One question needing links: search. Fresh events: news. Read a known page: extract. - Need answers with source text in one hop: search-extract. Many queries (research, SEO, monitoring): batch (~$0.0032/query). ## Pages - Pricing: https://x402serps.com/pricing - Docs: https://x402serps.com/docs - MCP: https://x402serps.com/mcp - Terms: https://x402serps.com/terms Privacy: https://x402serps.com/privacy ## Data source Results come from a third-party search provider; we monitor its uptime on /status and are adding a backup provider (automatic failover is built in). Status: https://x402serps.com/api/status. Contact: hello@x402serps.com ## Client compatibility Payments use x402 protocol v2 (x402Version: 2). Unpaid calls return HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON) and the same JSON in the body: accepts[] lists Base (eip155:8453) and Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) USDC, plus Bazaar discovery metadata. Pay by retrying with a PAYMENT-SIGNATURE header. Recommended client: @x402/fetch 2.x. Legacy x402 v1 clients (x402-fetch / x402-axios 1.2.x) still work: add the request header "X402-Version: 1" to get a v1 challenge, and the X-PAYMENT header is accepted as before. Older x402 0.x clients and hand-built payloads are rejected with invalid_payload. ```js // v2, Base. npm i @x402/fetch @x402/evm viem import { wrapFetchWithPayment, x402Client } from "@x402/fetch"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; const client = new x402Client().register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.EVM_PRIVATE_KEY))); const pay = wrapFetchWithPayment(fetch, client); // v2, Solana. npm i @x402/fetch @x402/svm @solana/kit@^8 import { wrapFetchWithPayment, x402Client } from "@x402/fetch"; import { ExactSvmScheme } from "@x402/svm/exact/client"; import { createKeyPairSignerFromBytes, getBase58Encoder } from "@solana/kit"; const signer = await createKeyPairSignerFromBytes(getBase58Encoder().encode(process.env.SOLANA_PRIVATE_KEY)); const pay = wrapFetchWithPayment(fetch, new x402Client().register("solana:*", new ExactSvmScheme(signer))); // v1 (legacy), Base. npm i x402-fetch@^1.2 import { wrapFetchWithPayment, createSigner } from "x402-fetch"; const base = await createSigner("base", process.env.EVM_PRIVATE_KEY); const pay = wrapFetchWithPayment(fetch, base); // v1 (legacy), Solana only, no EVM key needed import { wrapFetchWithPayment, createSigner } from "x402-fetch"; const sol = await createSigner("solana", process.env.SOLANA_PRIVATE_KEY); const pay = wrapFetchWithPayment(fetch, sol); // Then, with any of the above (v1 clients must send X402-Version: 1): const r = await pay("https://x402serps.com/api/v1/search", { method: "POST", headers: { "content-type": "application/json", "X402-Version": "1" /* v1 clients only */ }, body: JSON.stringify({ q: "hello" }), }); console.log(await r.json()); ``` ## Caching Results are cached for about 1 hour and cached responses carry the header X-Cache: HIT. Credit-key (Bearer xs_) calls to search, news, images, places, shopping, scholar and videos that are fully served from cache cost 50% (half the credits are refunded automatically; see X-Credits-Refunded). Cached results paid via x402 are charged at full price, because x402 settles before the request runs. ## Research & visibility notes research uses an extractive summarizer (key sentences ranked by query overlap and cross-source agreement, cited as [n]); no LLM, so no hallucinated text, but summaries are quotations rather than prose. visibility checks the top 10 organic per keyword; aiOverview is reported only when Serper returns it (often absent). --- # Agent guide (agents.md) # x402serps > Pay-per-call web search (search results), news, and clean page extraction for AI agents. USDC on Base or Solana via x402. No account or API key. ## Endpoints (all POST JSON; unpaid requests return HTTP 402 with x402 payment requirements) - /api/v1/search $0.004 {"q":"...","num":10} (also GET ?q=&num=) -> {query,provider,results:[{position,title,url,snippet}]} - /api/v1/news $0.004 {"q":"...","num":10} -> {query,provider,results:[{position,title,url,snippet,source,date}]} - /api/v1/extract $0.003 {"url":"https://...","maxChars":50000} -> {url,finalUrl,title,contentType,markdown,length,truncated} - /api/v1/search-extract $0.02 {"q":"...","n":3} -> search results (top n, max 5) each with extracted markdown in "content" - /api/v1/batch $0.08 {"queries":["...", ...up to 25],"num":10} -> {count,results:[{query,provider,results}]} - /api/v1/images $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Image: image URL, thumbnail, size) - /api/v1/places $0.004 {"q":"...","num":10,"gl":"us","location":"London"} -> {query,provider,results:[...]} (Maps/places: address, rating, phone, website, lat/lng) - /api/v1/shopping $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Shopping: product, price, store, rating) - /api/v1/scholar $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Scholar: papers, year, citations, PDF) - /api/v1/videos $0.004 {"q":"...","num":10,"gl":"us"} -> {query,provider,results:[...]} (Video: title, channel, duration, date) - /api/v1/answer $0.02 {"q":"...","n":4,"freshness":"week"} -> {query,answer,method,model,citations:[{id,title,url}]} (search + read top pages + cited answer; currently uses extractive summaries, i.e. quoted key sentences, not LLM prose) - /api/v1/crawl $0.002 per page {"url":"https://...","limit":10,"include":"/blog"} -> {url,count,pages:[{url,title,markdown}]} (same-host crawl, 1-50 pages, charged for limit) - /api/v1/map $0.002 {"url":"example.com","limit":200,"search":"docs"} -> {url,count,source,urls} (up to 1000 URLs from sitemaps + links) - Search/news filters: freshness (hour|day|week|month|year), dateFrom/dateTo (YYYY-MM-DD), raw tbs, page (pagination), num up to 100, gl, hl. - Multi-URL extract: {"urls":[... up to 20]} at $0.003 per URL (x402 v2 or credits). Research: "answer":true adds a cited answer (currently extractive summaries). - /api/v1/research $0.08 {"q":"...","n":5,"maxChars":20000} -> {query,method:"extractive",summary,keyPoints:[{text,source}],sources:[{id,title,url,excerpts}],related} (deep research: search + read top 3-8 pages, cited brief; ~5-20s) - /api/v1/visibility $0.10 flat {"brand":"example.com","keywords":["k1","... up to 10"],"gl":"us"} -> {domainTip (StableDomains: https://stabledomains.net),score 0-100,keywordsFound,topCompetitors,results:[{keyword,found,rank,url,features:{aiOverview,answerBox,peopleAlsoAsk,knowledgeGraph},competitors,score}]} (AI/SEO visibility) - /api/v1/competitor-report $0.30 {"domain":"example.com","keywords":["k1","... up to 8"],"gl":"us"} -> rankings per keyword, ads/advertisers, SERP features, share of voice, top competitors + their top pages, your top pages - /api/v1/leads $0.25 {"q":"dentists","location":"Leeds, UK","num":10} -> up to 20 Maps/places businesses enriched with business contact details only: role emails (info@, sales@, contact@), business phones and social links from their sites; personal-looking emails dropped; opt-outs (https://x402serps.com/opt-out) honoured; use subject to UK GDPR/PECR terms - /api/v1/seo-audit $0.20 {"domain":"example.com","brand":"Example","pages":8} -> indexed pages, title/meta/h1/canonical/noindex/alt checks, robots.txt, sitemap, brand rank, score 0-100, domainTip (find a name, then register it on StableDomains: https://stabledomains.net) - /api/v1/news-digest $0.05 {"topics":["t1","... up to 5"],"since":"day","num":10} -> deduplicated news per topic, top sources, text digest ## Monitors (credit key only) POST /api/v1/monitors with Authorization: Bearer xs_... and {"type":"rank","domain":"example.com","keywords":["k1",".. up to 10"],"gl":"us","webhook":"https://..."} (max(20, 10×keywords) credits/day) or {"type":"brand","query":"Example Inc","webhook":"https://..."} (3 credits/day). Runs immediately, then daily (06:00 UTC); first day charged at creation; pauses when credits run out. GET /api/v1/monitors lists, GET /api/v1/monitors/{id}?limit=7 returns results, PATCH {"active":true|false}, DELETE removes. Webhook gets POST JSON {monitor, result} per run. ## Integrations SDKs (packages coming soon; source and examples at https://x402serps.com/integrations) - JS class X402Serps, Python X402Serps. Tool schemas for OpenAI/Claude function calling: https://x402serps.com/tools.json Base URL: https://x402serps.com ## Free trial Free trial: send header X-Trial: 1 (no X-PAYMENT) to /api/v1/search, news, extract (and images, places, shopping, scholar, videos). research and visibility are paid-only (not in the trial). 25 free calls per network (IPv4 /24), max 10/minute; response header X-Trial-Remaining shows what's left. When used up, you get the normal 402 (header X-Trial-Status explains). Also works over MCP: send X-Trial: 1 on the MCP HTTP request. curl -X POST https://x402serps.com/api/v1/search -H "content-type: application/json" -H "X-Trial: 1" -d '{"q":"x402"}' ## MCP https://x402serps.com/api/mcp (streamable HTTP JSON). Tools (16): web_search {query,num}, news_search {query,num}, extract {url,maxChars}, search_extract {query,n,maxChars}, batch_search {queries,num}, image_search {query,num,gl}, places_search {query,num,gl,location}, shopping_search {query,num,gl}, scholar_search {query,num,gl}, video_search {query,num,gl}, deep_research {query,n,maxChars}, ai_visibility_check {brand,keywords,gl}, competitor_report {domain,keywords,gl}, lead_finder {query,location,num}, seo_audit {domain,brand,pages}, news_digest {topics,since,num}. Credit keys work over MCP too (Authorization: Bearer xs_...). Protocol version 2025-06-18 (also 2025-03-26, 2024-11-05). Send x402 payment in X-PAYMENT header. ## Data source Search results come from a third-party search provider. Extraction fetches the target URL directly. ## Discovery - Status: https://x402serps.com/api/status (HTML: /status) - A2A agent card: https://x402serps.com/.well-known/agent.json - OpenAPI: https://x402serps.com/openapi.json - x402: https://x402serps.com/.well-known/x402 ## Payment Solana: every paid endpoint also accepts USDC on Solana (asset EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v, fee paid by facilitator). The 402 lists both options in accepts[]; your client picks one. scheme exact, network base, asset USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) (payTo is given in each 402 challenge). Failed requests (4xx/5xx) are not settled. Client: npm x402-fetch / x402-axios (wrapFetchWithPayment). Contact: hello@x402serps.com ## Client compatibility Payments use x402 protocol v2 (x402Version: 2). Unpaid calls return HTTP 402 with a PAYMENT-REQUIRED header (base64 JSON) and the same JSON in the body: accepts[] lists Base (eip155:8453) and Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp) USDC, plus Bazaar discovery metadata. Pay by retrying with a PAYMENT-SIGNATURE header. Recommended client: @x402/fetch 2.x. Legacy x402 v1 clients (x402-fetch / x402-axios 1.2.x) still work: add the request header "X402-Version: 1" to get a v1 challenge, and the X-PAYMENT header is accepted as before. Older x402 0.x clients and hand-built payloads are rejected with invalid_payload. ```js // v2, Base. npm i @x402/fetch @x402/evm viem import { wrapFetchWithPayment, x402Client } from "@x402/fetch"; import { ExactEvmScheme } from "@x402/evm/exact/client"; import { privateKeyToAccount } from "viem/accounts"; const client = new x402Client().register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.EVM_PRIVATE_KEY))); const pay = wrapFetchWithPayment(fetch, client); // v2, Solana. npm i @x402/fetch @x402/svm @solana/kit@^8 import { wrapFetchWithPayment, x402Client } from "@x402/fetch"; import { ExactSvmScheme } from "@x402/svm/exact/client"; import { createKeyPairSignerFromBytes, getBase58Encoder } from "@solana/kit"; const signer = await createKeyPairSignerFromBytes(getBase58Encoder().encode(process.env.SOLANA_PRIVATE_KEY)); const pay = wrapFetchWithPayment(fetch, new x402Client().register("solana:*", new ExactSvmScheme(signer))); // v1 (legacy), Base. npm i x402-fetch@^1.2 import { wrapFetchWithPayment, createSigner } from "x402-fetch"; const base = await createSigner("base", process.env.EVM_PRIVATE_KEY); const pay = wrapFetchWithPayment(fetch, base); // v1 (legacy), Solana only, no EVM key needed import { wrapFetchWithPayment, createSigner } from "x402-fetch"; const sol = await createSigner("solana", process.env.SOLANA_PRIVATE_KEY); const pay = wrapFetchWithPayment(fetch, sol); // Then, with any of the above (v1 clients must send X402-Version: 1): const r = await pay("https://x402serps.com/api/v1/search", { method: "POST", headers: { "content-type": "application/json", "X402-Version": "1" /* v1 clients only */ }, body: JSON.stringify({ q: "hello" }), }); console.log(await r.json()); ``` ## Caching Results are cached for about 1 hour and cached responses carry the header X-Cache: HIT. Credit-key (Bearer xs_) calls to search, news, images, places, shopping, scholar and videos that are fully served from cache cost 50% (half the credits are refunded automatically; see X-Credits-Refunded). Cached results paid via x402 are charged at full price, because x402 settles before the request runs. ## Research & visibility notes research uses an extractive summarizer (key sentences ranked by query overlap and cross-source agreement, cited as [n]); no LLM, so no hallucinated text, but summaries are quotations rather than prose. visibility checks the top 10 organic per keyword; aiOverview is reported only when Serper returns it (often absent). ## Prepaid credits Prepaid credits (card via Stripe): $5 = 5,500 credits (1,375 searches), $20 = 24,000 credits (6,000 searches), $100 = 130,000 credits (32,500 searches). Buy at https://x402serps.com/pricing#credits; your API key (xs_...) is shown once after checkout. Send header Authorization: Bearer xs_... on any /api/v1 endpoint instead of paying with x402. 1 credit = $0.001: search/news/images/places/shopping/scholar/videos 4, extract 3 per URL, crawl 2 per page, map 2, answer 20, search-extract 20, batch 80, research 80, visibility 100, news-digest 50, seo-audit 200, leads 250, competitor-report 300. Response header X-Credits-Remaining. Balance: GET /api/v1/balance with the same header. Out of credits -> normal 402 (header X-Credits-Status). Unknown key -> 401. --- # Skill (skill.md) --- name: x402serps description: Real-time web search, cited answers, page extraction, site crawl/map, research and SEO data for agents. Use when you need current web information, sources with URLs, or the text of web pages. --- # x402serps agent skill Base URL: https://x402serps.com · MCP: https://x402serps.com/api/mcp (streamable HTTP) · OpenAPI: /openapi.json · Tools: /tools.json ## Setup (pick one auth) 1. Free trial: send header `X-Trial: 1` (25 calls per network, 10/min; search, news, single extract, images, places, shopping, scholar, videos). 2. Prepaid credit key: `Authorization: Bearer xs_...` (buy at https://x402serps.com/pricing#credits; 1 credit = $0.001). 3. x402: call without auth, get HTTP 402 with PAYMENT-REQUIRED, pay USDC on Base or Solana, retry with PAYMENT-SIGNATURE. MCP install: Cursor `cursor://anysphere.cursor-deeplink/mcp/install?name=x402serps&config=eyJ1cmwiOiJodHRwczovL3g0MDJzZXJwcy5jb20vYXBpL21jcCIsImhlYWRlcnMiOnsiWC1UcmlhbCI6IjEifX0=` · Claude Code `claude mcp add --transport http x402serps https://x402serps.com/api/mcp --header "X-Trial: 1"` · VS Code `code --add-mcp '{"name":"x402serps","type":"http","url":"https://x402serps.com/api/mcp","headers":{"X-Trial":"1"}}'` ## Which endpoint to use (POST JSON) | Need | Endpoint | Price | |---|---|---| | Current facts, links | `/api/v1/search {"q","num","freshness","page"}` | $0.004 | | A direct answer with citations | `/api/v1/answer {"q"}` | $0.02 | | News | `/api/v1/news {"q","freshness":"day"}` | $0.004 | | Text of known URLs | `/api/v1/extract {"url"}` or `{"urls":[...≤20]}` | $0.003/URL | | Search + page text | `/api/v1/search-extract {"q","n":3}` | $0.02 | | Whole site content | `/api/v1/crawl {"url","limit":10}` | $0.002/page | | List a site's URLs | `/api/v1/map {"url"}` | $0.002 | | Multi-source brief | `/api/v1/research {"q","answer":true}` | $0.08 | | Images/places/shopping/scholar/videos | `/api/v1/ {"q"}` | $0.004 | Filters on search/news: `freshness` hour|day|week|month|year, `dateFrom`/`dateTo` YYYY-MM-DD, `page` 1-10, `num` up to 100 (billed per 10 results), `gl`, `hl`. ## Tips - Prefer `answer` for questions, `search` for link lists, `extract` with `urls[]` to read several known pages in one call. - Cite the `url` fields you used. Results are cached for about 1 hour; cached responses carry X-Cache: HIT; credit-key calls to search/news/verticals fully served from cache cost 50%, x402-paid cached calls are full price. - Errors: 400 bad input, 401 unknown key, 402 payment needed (check X-Credits-Status / X-Trial-Status), 422 page could not be fetched. --- # OpenAPI 3.1 spec (also at https://x402serps.com/openapi.json) ```json { "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Machine-readable code or short message" }, "message": { "type": "string" }, "buy": { "type": "string", "format": "uri" } }, "required": [ "error" ] }, "PaymentRequired": { "type": "object", "properties": { "x402Version": { "type": "integer" }, "error": { "type": "string" }, "resource": { "type": "object" }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string" }, "network": { "type": "string" }, "amount": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" } } } }, "extensions": { "type": "object" } }, "required": [ "x402Version", "accepts" ] } }, "securitySchemes": { "creditKey": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Send as Authorization: Bearer xs_... Prepaid credit API key (xs_...), bought at /pricing#credits. 1 credit = $0.001. Alternative to x402 payment." } } }, "openapi": "3.1.0", "info": { "title": "x402serps", "version": "1.3.1", "license": { "name": "Proprietary", "url": "https://x402serps.com/terms" }, "termsOfService": "https://x402serps.com/terms", "contact": { "email": "hello@x402serps.com" }, "x-guidance": "POST JSON to any /api/v1 endpoint. Unpaid calls return HTTP 402 with x402 v2 PAYMENT-REQUIRED (USDC on Base or Solana); retry with PAYMENT-SIGNATURE (v2) or X-PAYMENT (v1). Start with /api/v1/search {q}. Bundles: /api/v1/competitor-report {domain,keywords}, /api/v1/leads {q,location}, /api/v1/seo-audit {domain}, /api/v1/news-digest {topics}. Alternative auth: Authorization: Bearer xs_... prepaid credit key. Free tier: the MCP server at https://x402serps.com/api/mcp gives 20 free web_search/extract calls a day with no payment or key.", "description": "Pay-per-call web search, news, and extraction via x402 (HTTP 402, then retry with X-PAYMENT header). USDC on Base or Solana. Or prepaid card credits: Authorization: Bearer xs_... (see /pricing#credits)." }, "servers": [ { "url": "https://x402serps.com" } ], "paths": { "/api/v1/search": { "post": { "operationId": "search", "summary": "x402serps: real-time web search results (title, url, snippet) for AI agents, one query, 10 results per $0.004 (num up to 100), with freshness/date-range filters and pagination", "x-price-usd": "0.004", "x-price-per": "10 results", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Search query (alias: query)" }, "num": { "type": "number", "description": "Results 1-100, default 10" }, "freshness": { "type": "string", "description": "Recency filter: hour, day, week, month or year" }, "dateFrom": { "type": "string", "description": "Custom date range start YYYY-MM-DD (with dateTo)" }, "dateTo": { "type": "string", "description": "Custom date range end YYYY-MM-DD" }, "tbs": { "type": "string", "description": "Raw tbs filter, e.g. qdr:w" }, "gl": { "type": "string", "description": "Country code" }, "hl": { "type": "string", "description": "Language code" }, "page": { "type": "number", "description": "Result page 1-10 (pagination)" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 }, "get": { "operationId": "search_get", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "summary": "Web search (GET)", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "num", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Results", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 } }, "/api/v1/news": { "post": { "operationId": "news", "summary": "x402serps: real-time News results (title, url, snippet, source, date) for one query, 10 results per $0.004 (num up to 100), with freshness/date-range filters and pagination", "x-price-usd": "0.004", "x-price-per": "10 results", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "News query (alias: query)" }, "num": { "type": "number", "description": "Results 1-100, default 10" }, "freshness": { "type": "string", "description": "Recency filter: hour, day, week, month or year" }, "dateFrom": { "type": "string", "description": "Custom date range start YYYY-MM-DD (with dateTo)" }, "dateTo": { "type": "string", "description": "Custom date range end YYYY-MM-DD" }, "tbs": { "type": "string", "description": "Raw tbs filter, e.g. qdr:w" }, "gl": { "type": "string", "description": "Country code" }, "hl": { "type": "string", "description": "Language code" }, "page": { "type": "number", "description": "Result page 1-10 (pagination)" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" }, "source": { "type": "string" }, "date": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 } }, "/api/v1/extract": { "post": { "operationId": "extract", "summary": "x402serps: fetch public http(s) URLs and return clean readable markdown text; one url or up to 20 urls in parallel, priced per URL (max 2MB page, 10s, output up to 100k chars)", "x-price-usd": "0.003", "x-price-per": "url", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.003000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "http(s) URL to fetch (or pass urls[] instead)" }, "urls": { "type": "array", "items": { "type": "string" }, "description": "Up to 20 URLs, fetched in parallel; charged per URL" }, "maxChars": { "type": "number", "description": "Max output chars, default 50000, max 100000" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "finalUrl": { "type": "string" }, "title": { "type": "string" }, "contentType": { "type": "string" }, "markdown": { "type": "string" }, "length": { "type": "number" }, "truncated": { "type": "boolean" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 3 } }, "/api/v1/search-extract": { "post": { "operationId": "search_extract", "summary": "x402serps: Web search plus clean extracted markdown of the top N results (default 3, max 5) in one call", "x-price-usd": "0.02", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Search query (alias: query)" }, "n": { "type": "number", "description": "Results to extract 1-5, default 3" }, "maxChars": { "type": "number", "description": "Max chars per page, default 15000" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" }, "content": { "type": "object", "properties": { "url": { "type": "string" }, "finalUrl": { "type": "string" }, "title": { "type": "string" }, "contentType": { "type": "string" }, "markdown": { "type": "string" }, "length": { "type": "number" }, "truncated": { "type": "boolean" } } }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 20 } }, "/api/v1/batch": { "post": { "operationId": "batch", "summary": "x402serps: up to 25 Web search queries in one paid call", "x-price-usd": "0.08", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.080000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "queries": { "type": "array", "items": { "type": "string" }, "description": "1-25 queries" }, "num": { "type": "number", "description": "Results per query 1-20, default 10" } }, "required": [ "queries" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "number" }, "results": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" } } } }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 80 } }, "/api/v1/images": { "post": { "operationId": "image_search", "summary": "x402serps: Image results (title, page url, imageUrl, thumbnail, size) for one query, up to 20", "x-price-usd": "0.004", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Query (alias: query)" }, "num": { "type": "number", "description": "Results 1-20, default 10" }, "gl": { "type": "string", "description": "Country code, e.g. us, gb" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "imageUrl": { "type": "string" }, "thumbnailUrl": { "type": "string" }, "source": { "type": "string" }, "width": { "type": "number" }, "height": { "type": "number" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 } }, "/api/v1/places": { "post": { "operationId": "places_search", "summary": "x402serps: Maps/places results (name, address, rating, phone, website, lat/lng) for one query, up to 20", "x-price-usd": "0.004", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Query (alias: query)" }, "num": { "type": "number", "description": "Results 1-20, default 10" }, "gl": { "type": "string", "description": "Country code, e.g. us, gb" }, "location": { "type": "string", "description": "Optional location, e.g. London, United Kingdom" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "address": { "type": "string" }, "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "category": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "cid": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 } }, "/api/v1/shopping": { "post": { "operationId": "shopping_search", "summary": "x402serps: Shopping product results (title, price, store, rating, url, image) for one query, up to 20", "x-price-usd": "0.004", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Query (alias: query)" }, "num": { "type": "number", "description": "Results 1-20, default 10" }, "gl": { "type": "string", "description": "Country code, e.g. us, gb" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "source": { "type": "string" }, "price": { "type": "string" }, "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "imageUrl": { "type": "string" }, "productId": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 } }, "/api/v1/scholar": { "post": { "operationId": "scholar_search", "summary": "x402serps: Scholar results (title, url, snippet, publication, year, citations, pdf) for one query, up to 20", "x-price-usd": "0.004", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Query (alias: query)" }, "num": { "type": "number", "description": "Results 1-20, default 10" }, "gl": { "type": "string", "description": "Country code, e.g. us, gb" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" }, "publicationInfo": { "type": "string" }, "year": { "type": "number" }, "citedBy": { "type": "number" }, "pdfUrl": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 } }, "/api/v1/videos": { "post": { "operationId": "video_search", "summary": "x402serps: Video results (title, url, channel, duration, date, thumbnail) for one query, up to 20", "x-price-usd": "0.004", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.004000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Query (alias: query)" }, "num": { "type": "number", "description": "Results 1-20, default 10" }, "gl": { "type": "string", "description": "Country code, e.g. us, gb" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "snippet": { "type": "string" }, "channel": { "type": "string" }, "duration": { "type": "string" }, "date": { "type": "string" }, "imageUrl": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 4 } }, "/api/v1/research": { "post": { "operationId": "deep_research", "summary": "x402serps: deep research — web search, extract the top 3-8 pages in parallel, return a concise cited brief (extractive key sentences) plus source excerpts", "x-price-usd": "0.08", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.080000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Research question (alias: query)" }, "n": { "type": "number", "description": "Pages to read 3-8, default 5" }, "maxChars": { "type": "number", "description": "Max chars read per page, default 20000" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "provider": { "type": "string" }, "method": { "type": "string" }, "summary": { "type": "string" }, "keyPoints": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "source": { "type": "number" } } } }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" }, "position": { "type": "number" }, "snippet": { "type": "string" }, "excerpts": { "type": "array", "items": { "type": "string" } }, "extracted": { "type": "boolean" }, "error": { "type": "string" } } } }, "related": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" } } } }, "elapsedMs": { "type": "number" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 80 } }, "/api/v1/visibility": { "post": { "operationId": "ai_visibility_check", "summary": "x402serps: AI/SEO visibility check — for 1-10 keywords, where a brand or domain ranks in search results, plus AI Overview, answer box, People Also Ask and knowledge graph presence, top competitors and a 0-100 score (flat price)", "x-price-usd": "0.10", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.100000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand": { "type": "string", "description": "Brand name or domain, e.g. stripe.com" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "1-10 keywords" }, "gl": { "type": "string", "description": "Country code, default us" } }, "required": [ "brand", "keywords" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "brand": { "type": "string" }, "domain": { "type": "string" }, "gl": { "type": "string" }, "score": { "type": "number" }, "keywordsFound": { "type": "number" }, "keywordsChecked": { "type": "number" }, "topCompetitors": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "keywords": { "type": "number" } } } }, "results": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "found": { "type": "boolean" }, "rank": { "type": "number" }, "url": { "type": "string" }, "mentionedInResults": { "type": "boolean" }, "score": { "type": "number" }, "features": { "type": "object", "properties": { "aiOverview": { "type": "object", "properties": { "present": { "type": "boolean" }, "brand": { "type": "boolean" } } }, "answerBox": { "type": "object", "properties": { "present": { "type": "boolean" }, "brand": { "type": "boolean" } } }, "peopleAlsoAsk": { "type": "object", "properties": { "present": { "type": "boolean" }, "brand": { "type": "boolean" } } }, "knowledgeGraph": { "type": "object", "properties": { "present": { "type": "boolean" }, "brand": { "type": "boolean" } } } } }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "rank": { "type": "number" } } } } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 100 } }, "/api/v1/competitor-report": { "post": { "operationId": "competitor_report", "summary": "x402serps: competitor report — for a domain and 1-8 keywords: search rankings, ads/advertisers, SERP features, share of voice, top competitors with their top pages, and the domain's own top pages", "x-price-usd": "0.30", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.300000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Your domain, e.g. example.com" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "1-8 keywords" }, "gl": { "type": "string", "description": "Country code, default us" } }, "required": [ "domain", "keywords" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "gl": { "type": "string" }, "summary": { "type": "object", "properties": { "keywordsChecked": { "type": "number" }, "keywordsRanked": { "type": "number" }, "avgRank": { "type": "number" }, "shareOfVoice": { "type": "number" }, "keywordsWithAds": { "type": "number" }, "topCompetitor": { "type": "string" } } }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string" }, "rank": { "type": "number" }, "url": { "type": "string" }, "adsCount": { "type": "number" } } } }, "competitors": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "keywords": { "type": "number" }, "bestRank": { "type": "number" }, "avgRank": { "type": "number" }, "shareOfVoice": { "type": "number" } } } }, "topPages": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" } } } }, "advertisers": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 300 } }, "/api/v1/leads": { "post": { "operationId": "lead_finder", "summary": "x402serps: local lead finder — Maps/places businesses for a query and location (up to 20) enriched with business contact details (role emails such as info@/sales@, business phones, social links; personal-looking emails dropped; opt-outs honoured) extracted from each business website and contact page", "x-price-usd": "0.25", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.250000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Business type, e.g. dentists (alias: query)" }, "location": { "type": "string", "description": "e.g. Leeds, United Kingdom" }, "num": { "type": "number", "description": "Businesses 1-20, default 20" }, "gl": { "type": "string", "description": "Country code" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "location": { "type": "string" }, "count": { "type": "number" }, "withEmail": { "type": "number" }, "withPhone": { "type": "number" }, "leads": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "string" }, "phone": { "type": "string" }, "website": { "type": "string" }, "rating": { "type": "number" }, "ratingCount": { "type": "number" }, "category": { "type": "string" }, "emails": { "type": "array", "items": { "type": "string" } }, "sitePhones": { "type": "array", "items": { "type": "string" } }, "socials": { "type": "array", "items": { "type": "string" } }, "contactPage": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 250 } }, "/api/v1/seo-audit": { "post": { "operationId": "seo_audit", "summary": "x402serps: SEO audit — a domain's search-indexed pages, title/meta description/h1/canonical/noindex/alt checks on up to 8 top pages, robots.txt and sitemap, brand-query ranking and a 0-100 score", "x-price-usd": "0.20", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.200000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain, e.g. example.com" }, "brand": { "type": "string", "description": "Brand query, default from domain" }, "pages": { "type": "number", "description": "Pages to audit 1-8, default 6" }, "gl": { "type": "string", "description": "Country code" } }, "required": [ "domain" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string" }, "score": { "type": "number" }, "brandQuery": { "type": "string" }, "brandRank": { "type": "number" }, "indexedSampleCount": { "type": "number" }, "robotsTxt": { "type": "boolean" }, "sitemapXml": { "type": "boolean" }, "siteIssues": { "type": "array", "items": { "type": "string" } }, "pages": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "number" }, "title": { "type": "string" }, "metaDescription": { "type": "string" }, "h1Count": { "type": "number" }, "canonical": { "type": "string" }, "wordCount": { "type": "number" }, "issues": { "type": "array", "items": { "type": "string" } }, "score": { "type": "number" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 200 } }, "/api/v1/news-digest": { "post": { "operationId": "news_digest", "summary": "x402serps: news digest — News for 1-5 topics, deduplicated, with top sources per topic and a compact text digest; optional since=hour|day|week|month", "x-price-usd": "0.05", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.050000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "string" }, "description": "1-5 topics" }, "num": { "type": "number", "description": "Items per topic 3-20, default 10" }, "since": { "type": "string", "description": "hour, day, week or month" }, "gl": { "type": "string", "description": "Country code" } }, "required": [ "topics" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "topics": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "count": { "type": "number" }, "headline": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "source": { "type": "string" }, "date": { "type": "string" }, "snippet": { "type": "string" } } } } } } }, "totalItems": { "type": "number" }, "digest": { "type": "string" }, "generatedAt": { "type": "string" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 50 } }, "/api/v1/answer": { "post": { "operationId": "answer", "summary": "x402serps: cited answer — web search, read the top pages, and return a short answer with numbered citations (currently uses extractive summaries)", "x-price-usd": "0.02", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.020000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "q": { "type": "string", "description": "Question (alias: query)" }, "n": { "type": "number", "description": "Pages to read 2-6, default 4" }, "freshness": { "type": "string", "description": "hour, day, week, month or year" }, "gl": { "type": "string", "description": "Country code" } }, "required": [ "q" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" }, "answer": { "type": "string" }, "method": { "type": "string" }, "model": { "type": "string" }, "citations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "title": { "type": "string" }, "url": { "type": "string" } } } }, "elapsedMs": { "type": "number" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 20 } }, "/api/v1/crawl": { "post": { "operationId": "crawl_site", "summary": "x402serps: crawl a website — breadth-first from a start URL on the same host, returning clean markdown for up to 50 pages; priced per page of the requested limit", "x-price-usd": "0.002", "x-price-per": "page", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Start URL" }, "limit": { "type": "number", "description": "Max pages 1-50, default 10 (you are charged for the limit)" }, "maxChars": { "type": "number", "description": "Max chars per page, default 8000" }, "include": { "type": "string", "description": "Only follow paths containing this substring" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "count": { "type": "number" }, "pages": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "markdown": { "type": "string" }, "error": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 2 } }, "/api/v1/map": { "post": { "operationId": "map_site", "summary": "x402serps: map a website — discover up to 1000 URLs on a domain from robots.txt sitemaps and on-page links (flat price)", "x-price-usd": "0.002", "x-payment-info": { "price": { "mode": "fixed", "currency": "USD", "amount": "0.002000" }, "protocols": [ { "x402": {} } ] }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Site URL or domain" }, "limit": { "type": "number", "description": "Max URLs 1-1000, default 200" }, "search": { "type": "string", "description": "Only return URLs containing this substring" } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "OK", "headers": { "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "RateLimit-Policy": { "description": "Window policy, e.g. 10;w=60", "schema": { "type": "string" } }, "X-Trial-Remaining": { "description": "Free trial calls left (25 total)", "schema": { "type": "integer" } }, "X-Credits-Remaining": { "description": "Prepaid credits left on the key", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "count": { "type": "number" }, "source": { "type": "string" }, "urls": { "type": "array", "items": { "type": "string" } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream search provider failure (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ {}, { "creditKey": [] } ], "x-credits": 2 } }, "/api/v1/balance": { "get": { "operationId": "get_balance", "summary": "Prepaid credit balance for an API key", "security": [ { "creditKey": [] } ], "responses": { "200": { "description": "Balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "credits": { "type": "integer" }, "usdValue": { "type": "number" }, "purchased": { "type": "integer" }, "pack": { "type": "string" }, "created": { "type": "string", "format": "date-time" }, "lastUsed": { "type": [ "string", "null" ], "format": "date-time" } } } } } }, "401": { "description": "Missing or unknown key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stripe/checkout": { "post": { "operationId": "create_checkout", "security": [], "summary": "Create a Stripe Checkout session for a credit pack (starter $5/5,500 credits, pro $20/24,000, scale $100/130,000; 1 credit = $0.001). Returns {url}.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pack": { "type": "string", "enum": [ "starter", "pro", "scale" ] } }, "required": [ "pack" ] } } } }, "responses": { "200": { "description": "Checkout session", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ] } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/monitors": { "post": { "operationId": "create_monitor", "summary": "Create a daily rank (max(20, 10×keywords) credits/day) or brand/news (30 credits/day) monitor; runs now, then daily", "security": [ { "creditKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "rank", "brand" ] }, "domain": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" }, "description": "rank: 1-10" }, "query": { "type": "string", "description": "brand: brand or topic" }, "gl": { "type": "string" }, "webhook": { "type": "string", "description": "optional https URL, POSTed each run" } }, "required": [ "type" ] } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "monitor": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "rank", "brand" ] }, "active": { "type": "boolean" }, "created": { "type": "string" } } }, "result": { "type": "object" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "x402 payment required (USDC on Base or Solana). The PAYMENT-REQUIRED header carries the base64 challenge; the body mirrors it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "list_monitors", "summary": "List your monitors", "security": [ { "creditKey": [] } ], "responses": { "200": { "description": "Monitors", "content": { "application/json": { "schema": { "type": "object", "properties": { "monitors": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "rank", "brand" ] }, "active": { "type": "boolean" }, "created": { "type": "string" } } } } } } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "headers": { "Retry-After": { "description": "Seconds to wait", "schema": { "type": "integer" } }, "RateLimit-Limit": { "description": "Requests allowed per window (free trial: 10 per 60 s)", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/monitors/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "get_monitor", "summary": "Monitor and recent results (?limit=)", "security": [ { "creditKey": [] } ], "responses": { "200": { "description": "Monitor", "content": { "application/json": { "schema": { "type": "object", "properties": { "monitor": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "rank", "brand" ] }, "active": { "type": "boolean" }, "created": { "type": "string" } } }, "results": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "update_monitor", "summary": "Pause/resume {active}", "security": [ { "creditKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "active": { "type": "boolean" } }, "required": [ "active" ] } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "monitor": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "rank", "brand" ] }, "active": { "type": "boolean" }, "created": { "type": "string" } } } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete_monitor", "summary": "Delete monitor", "security": [ { "creditKey": [] } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "description": "Missing or unknown API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error (not charged)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } } ```