{"openapi":"3.1.0","info":{"title":"PennyAPI","description":"PennyAPI provides x402-paid real-time web search and structured local-business Places search for AI agents, plus seller preflight, robots decisions, domain deltas, and Texas childcare Regulatory Watch.","version":"9.2.0","contact":{"email":"alerts@pennyregwatch.com"},"x-guidance":"Use POST /v1/search for richer Firecrawl-backed current-information grounding at $0.004. Use POST /v1/search/lite for low-cost first-hop web search at $0.001 with up to 5 ranked results. Use /web/places for local businesses and places."},"paths":{"/v1/search":{"post":{"summary":"Real-time web search for AI agents — current information, research, news & web grounding","description":"Primary agent-native paid search surface. JSON in, ranked current web results out.","operationId":"search_the_web_for_current_information_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["ok","tool","schema_version","query","freshness","count","results","economics","retrieved_at","latency_ms"],"properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"schema_version":{"type":"string"},"query":{"type":"string"},"freshness":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["position","title","url"],"properties":{"position":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"source_domain":{"type":"string"},"published_at":{"type":["string","null"]}}}},"economics":{"type":"object","required":["price_usd","currency","network","amount_atomic","cost_per_result_usd"],"properties":{"price_usd":{"type":"number"},"currency":{"type":"string"},"network":{"type":"string"},"amount_atomic":{"type":"string"},"cost_per_result_usd":{"type":["number","null"]}}},"retrieved_at":{"type":"string"},"latency_ms":{"type":"number"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-price":0.004,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.004000"}}},"get":{"summary":"Real-time web search for AI agents — current information, research, news & web grounding","description":"Canonical agent-native paid search surface: query parameters in, ranked current web results out.","operationId":"search_the_web_for_current_information_get","parameters":[{"name":"query","in":"query","required":true,"description":"Live web search query","schema":{"type":"string","minLength":2,"maxLength":500},"example":"latest artificial intelligence news"},{"name":"limit","in":"query","required":false,"description":"Number of ranked results, 1-10","schema":{"type":"integer","minimum":1,"maximum":10,"default":5}},{"name":"freshness","in":"query","required":false,"description":"Optional freshness window","schema":{"type":"string","enum":["hour","day","week","month","year"]}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["ok","tool","schema_version","query","freshness","count","results","economics","retrieved_at","latency_ms"],"properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"schema_version":{"type":"string"},"query":{"type":"string"},"freshness":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["position","title","url"],"properties":{"position":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"source_domain":{"type":"string"},"published_at":{"type":["string","null"]}}}},"economics":{"type":"object","required":["price_usd","currency","network","amount_atomic","cost_per_result_usd"],"properties":{"price_usd":{"type":"number"},"currency":{"type":"string"},"network":{"type":"string"},"amount_atomic":{"type":"string"},"cost_per_result_usd":{"type":["number","null"]}}},"retrieved_at":{"type":"string"},"latency_ms":{"type":"number"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-price":0.004,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.004000"}}}},"/v1/search/lite":{"post":{"summary":"Low-cost live web search for AI agents — $0.001 per call","operationId":"search_the_web_lite_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchLiteRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["ok","tool","schema_version","query","freshness","count","results","economics","retrieved_at","latency_ms"],"properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"schema_version":{"type":"string"},"query":{"type":"string"},"freshness":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["position","title","url"],"properties":{"position":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"source_domain":{"type":"string"},"published_at":{"type":["string","null"]}}}},"economics":{"type":"object","required":["price_usd","currency","network","amount_atomic","cost_per_result_usd"],"properties":{"price_usd":{"type":"number"},"currency":{"type":"string"},"network":{"type":"string"},"amount_atomic":{"type":"string"},"cost_per_result_usd":{"type":["number","null"]}}},"retrieved_at":{"type":"string"},"latency_ms":{"type":"number"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-price":0.001,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.001000"}}},"get":{"summary":"Low-cost live web search for AI agents — $0.001 per call","operationId":"search_the_web_lite_get","parameters":[{"name":"query","in":"query","required":true,"description":"Live web search query","schema":{"type":"string","minLength":2,"maxLength":500}},{"name":"limit","in":"query","required":false,"description":"Number of ranked results, 1-5","schema":{"type":"integer","minimum":1,"maximum":5,"default":5}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["ok","tool","schema_version","query","freshness","count","results","economics","retrieved_at","latency_ms"],"properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"schema_version":{"type":"string"},"query":{"type":"string"},"freshness":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","required":["position","title","url"],"properties":{"position":{"type":"integer"},"title":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"},"source_domain":{"type":"string"},"published_at":{"type":["string","null"]}}}},"economics":{"type":"object","required":["price_usd","currency","network","amount_atomic","cost_per_result_usd"],"properties":{"price_usd":{"type":"number"},"currency":{"type":"string"},"network":{"type":"string"},"amount_atomic":{"type":"string"},"cost_per_result_usd":{"type":["number","null"]}}},"retrieved_at":{"type":"string"},"latency_ms":{"type":"number"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-price":0.001,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.001000"}}}},"/v1/evidence-brief":{"post":{"summary":"Multi-source live-web evidence brief for AI agents","operationId":"build_live_web_evidence_brief","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceBriefRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-price":0.05,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.050000"}}}},"/web/places":{"post":{"summary":"Real-time local business and places search for AI agents","description":"Paid machine-native local business/place lookup. JSON in, structured places out.","operationId":"search_local_businesses_and_places_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlacesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["ok","tool","query","count","places","retrieved_at","latency_ms"],"properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"query":{"type":"string"},"count":{"type":"integer"},"places":{"type":"array","items":{"type":"object","required":["position","title","address"],"properties":{"position":{"type":"integer"},"title":{"type":"string"},"address":{"type":"string"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"rating":{"type":["number","null"]},"rating_count":{"type":["integer","null"]},"category":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"}}}},"retrieved_at":{"type":"string"},"latency_ms":{"type":"number"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-price":0.004,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.004000"}}},"get":{"summary":"Real-time local business and places search for AI agents","description":"Bazaar-discoverable GET compatibility route using the same Places fulfillment.","operationId":"search_local_businesses_and_places_get","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":500,"description":"Local business or places search query","title":"Query"},"description":"Local business or places search query"},{"name":"num","in":"query","required":false,"schema":{"type":"integer","maximum":10,"minimum":1,"description":"Number of places to return, 1-10","default":5,"title":"Num"},"description":"Number of places to return, 1-10"},{"name":"country","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"Optional 2-letter country code","title":"Country"},"description":"Optional 2-letter country code"},{"name":"lang","in":"query","required":false,"schema":{"anyOf":[{"type":"string","minLength":2,"maxLength":2},{"type":"null"}],"description":"Optional 2-letter language code","title":"Lang"},"description":"Optional 2-letter language code"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","required":["ok","tool","query","count","places","retrieved_at","latency_ms"],"properties":{"ok":{"type":"boolean"},"tool":{"type":"string"},"query":{"type":"string"},"count":{"type":"integer"},"places":{"type":"array","items":{"type":"object","required":["position","title","address"],"properties":{"position":{"type":"integer"},"title":{"type":"string"},"address":{"type":"string"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"rating":{"type":["number","null"]},"rating_count":{"type":["integer","null"]},"category":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"}}}},"retrieved_at":{"type":"string"},"latency_ms":{"type":"number"}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"x-price":0.004,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.004000"}}}},"/v1/x402/preflight":{"get":{"summary":"Preflight an x402 paid API before spending USDC","description":"Inspect an unfamiliar x402 endpoint before payment. Validate its live 402 challenge, Base/USDC payment surface, amount, payTo, TLS, redirects, manifest and provenance without sending funds.","operationId":"x402_seller_preflight_v1_x402_preflight_get","parameters":[{"name":"url","in":"query","required":true,"description":"Exact public x402 endpoint URL to check before paying","schema":{"type":"string","minLength":8,"maxLength":2048},"example":"https://example.com/paid-endpoint"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"tags":["x402","Payments","Agent Safety"],"x-price":0.001,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.001000"}}}},"/v1/robots":{"get":{"summary":"Check robots.txt crawl permission before scraping a URL","description":"Determine whether an AI agent or crawler such as GPTBot, ClaudeBot or Googlebot may fetch an exact page. Returns ALLOW/DENY, winning rule, crawl delay, sitemaps and live provenance.","operationId":"robots_v1_robots_get","parameters":[{"name":"target","in":"query","required":true,"description":"Exact public page URL or hostname to test","schema":{"type":"string","minLength":3,"maxLength":2048},"example":"https://example.com/private/page"},{"name":"user_agent","in":"query","required":false,"description":"Crawler product token","schema":{"type":"string","default":"*","minLength":1,"maxLength":200},"example":"GPTBot"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"tags":["Web","Crawler","Agent Utility"],"x-price":0.001,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.001000"}}}},"/v1/redirect":{"get":{"summary":"Resolve a URL redirect chain before following a link","operationId":"redirect_v1_redirect_get","parameters":[{"name":"target","in":"query","required":true,"description":"Public URL whose redirect chain should be resolved","schema":{"type":"string","minLength":3,"maxLength":2048},"example":"https://example.com"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"description":"Return the final URL, status, redirect count and chain for agent navigation, link verification and URL triage.","tags":["Web","URL","Agent Utility"],"x-price":0.001,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.001000"}}}},"/v1/metadata":{"get":{"summary":"Extract webpage metadata for research and URL triage","operationId":"metadata_v1_metadata_get","parameters":[{"name":"target","in":"query","required":true,"description":"Public webpage URL whose metadata should be extracted","schema":{"type":"string","minLength":3,"maxLength":2048},"example":"https://example.com"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"description":"Return page title, description, canonical URL, Open Graph and Twitter metadata from a public webpage.","tags":["Web","Research","Agent Utility"],"x-price":0.001,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.001000"}}}},"/v1/headers":{"get":{"summary":"Inspect HTTP, cache, CORS and security headers","operationId":"headers_v1_headers_get","parameters":[{"name":"target","in":"query","required":true,"description":"Public URL whose HTTP/cache/CORS/security headers should be inspected","schema":{"type":"string","minLength":3,"maxLength":2048},"example":"https://example.com"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"402":{"description":"Payment Required"}},"description":"Inspect a public URL's response headers for content type, caching, CORS, HSTS, CSP, framing and other integration/security signals.","tags":["Developer Tools","Web","Agent Utility"],"x-price":0.001,"x-payment-info":{"protocols":[{"x402":{}}],"price":{"mode":"fixed","currency":"USD","amount":"0.001000"}}}}},"components":{"schemas":{"EvidenceBriefRequest":{"properties":{"question":{"type":"string","maxLength":800,"minLength":10,"title":"Question","description":"Research question to investigate across multiple live-web searches"},"freshness":{"anyOf":[{"type":"string","pattern":"^(hour|day|week|month|year)$"},{"type":"null"}],"title":"Freshness","description":"Optional freshness window"},"max_sources":{"type":"integer","maximum":15.0,"minimum":4.0,"title":"Max Sources","description":"Maximum deduplicated sources returned","default":10}},"type":"object","required":["question"],"title":"EvidenceBriefRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"PlaceResult":{"properties":{"position":{"type":"integer","title":"Position"},"title":{"type":"string","title":"Title","default":""},"address":{"type":"string","title":"Address","default":""},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Latitude"},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Longitude"},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating"},"rating_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating Count"},"category":{"type":"string","title":"Category","default":""},"phone":{"type":"string","title":"Phone","default":""},"website":{"type":"string","title":"Website","default":""}},"type":"object","required":["position"],"title":"PlaceResult"},"PlacesRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":2,"title":"Query","description":"Local business or place search query"},"num":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Num","description":"Number of places to return, 1-10","default":5},"country":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2}$"},{"type":"null"}],"title":"Country","description":"Optional two-letter country code, e.g. us"},"lang":{"anyOf":[{"type":"string","pattern":"^[A-Za-z]{2,5}$"},{"type":"null"}],"title":"Lang","description":"Optional language code, e.g. en"}},"type":"object","required":["query"],"title":"PlacesRequest"},"PlacesResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"tool":{"type":"string","title":"Tool"},"query":{"type":"string","title":"Query"},"count":{"type":"integer","title":"Count"},"places":{"items":{"$ref":"#/components/schemas/PlaceResult"},"type":"array","title":"Places"},"retrieved_at":{"type":"string","title":"Retrieved At"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Latency Ms"}},"type":"object","required":["ok","tool","query","count","places","retrieved_at","latency_ms"],"title":"PlacesResponse"},"SearchEconomics":{"properties":{"price_usd":{"type":"number","title":"Price Usd"},"currency":{"type":"string","title":"Currency"},"network":{"type":"string","title":"Network"},"amount_atomic":{"type":"string","title":"Amount Atomic"},"cost_per_result_usd":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Cost Per Result Usd"}},"type":"object","required":["price_usd","currency","network","amount_atomic"],"title":"SearchEconomics"},"SearchLiteRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":2,"title":"Query","description":"Live web search query"},"limit":{"type":"integer","maximum":5.0,"minimum":1.0,"title":"Limit","description":"Number of ranked results, 1-5","default":5}},"type":"object","required":["query"],"title":"SearchLiteRequest"},"SearchRequest":{"properties":{"query":{"type":"string","maxLength":500,"minLength":2,"title":"Query","description":"Live web search query"},"limit":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Limit","description":"Number of ranked results, 1-10","default":5},"freshness":{"anyOf":[{"type":"string","pattern":"^(hour|day|week|month|year)$"},{"type":"null"}],"title":"Freshness","description":"Optional freshness window"}},"type":"object","required":["query"],"title":"SearchRequest"},"SearchResponse":{"properties":{"ok":{"type":"boolean","title":"Ok"},"tool":{"type":"string","title":"Tool"},"schema_version":{"type":"string","title":"Schema Version","default":"2.0"},"query":{"type":"string","title":"Query"},"freshness":{"type":"string","title":"Freshness"},"count":{"type":"integer","title":"Count"},"results":{"items":{"$ref":"#/components/schemas/SearchResult"},"type":"array","title":"Results"},"economics":{"$ref":"#/components/schemas/SearchEconomics"},"retrieved_at":{"type":"string","title":"Retrieved At"},"latency_ms":{"anyOf":[{"type":"integer"},{"type":"number"}],"title":"Latency Ms"}},"type":"object","required":["ok","tool","query","freshness","count","results","economics","retrieved_at","latency_ms"],"title":"SearchResponse"},"SearchResult":{"properties":{"position":{"type":"integer","title":"Position"},"title":{"type":"string","title":"Title"},"url":{"type":"string","title":"Url"},"description":{"type":"string","title":"Description","default":""},"source_domain":{"type":"string","title":"Source Domain","default":""},"published_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Published At"}},"type":"object","required":["position","title","url"],"title":"SearchResult"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}