{"openapi":"3.0.3","info":{"title":"GhostAPI — Semantic Web Scraper","description":"AI-powered semantic proxy that turns any public website into a structured JSON endpoint. Built for AI agents and LLM applications that need real-world data without building or maintaining scrapers. Every extraction is stored with an ethical semantic evaluation (cooperation index, social utility, environmental impact).","version":"2.0.0","contact":{"email":"dvd.pzz05@gmail.com"}},"servers":[{"url":"https://ghostapi.p.rapidapi.com","description":"Production (RapidAPI)"}],"security":[{"rapidApiKey":[]}],"paths":{"/health":{"get":{"summary":"Health check","operationId":"healthCheck","security":[],"responses":{"200":{"description":"Server is running","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"}}}}}}}}},"/v1/fetch":{"post":{"summary":"Semantic web scraper","description":"Scrape any public URL and extract structured JSON data using a natural language query. Results are cached automatically — repeated identical requests return instantly. Each extraction includes a semantic context evaluation produced by the LLM.","operationId":"fetchData","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["targetUrl","query"],"properties":{"targetUrl":{"type":"string","format":"uri","description":"Full URL of the public page to scrape","example":"https://www.immobiliare.it/annunci/123456/"},"query":{"type":"string","description":"Natural language description of the data to extract","example":"prezzo, superficie, numero locali, indirizzo"}}}}}},"responses":{"200":{"description":"Extracted data with semantic context","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["cache","live"],"description":"'cache' = served from cache (fast, free), 'live' = freshly scraped"},"data":{"type":"object","description":"Extracted fields as requested in the query"},"semanticContext":{"type":"object","description":"Ethical evaluation of the scraped content produced by the LLM","properties":{"indice_cooperazione":{"type":"number","format":"float","description":"0.0–1.0, cooperation and sharing index"},"utilita_sociale":{"type":"number","format":"float","description":"0.0–1.0, social utility score"},"impatto_ambientale":{"type":"string","enum":["positivo","neutro","negativo"]}}}}}}}},"400":{"description":"Invalid or missing body parameters"},"401":{"description":"Unauthorized — missing or invalid X-RapidAPI-Proxy-Secret"},"422":{"description":"Extracted data failed quality check"},"502":{"description":"Target site unreachable or blocked"}}}},"/v1/read":{"get":{"summary":"Historical data reader","description":"Returns the extraction history for a given URL from the HistoricalData store. No LLM tokens consumed — pure database read. Designed for AI agents that need to analyze patterns over time using accumulated semantic context vectors.","operationId":"readHistory","parameters":[{"name":"targetUrl","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"URL to retrieve history for","example":"https://example.com"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Max number of records to return"},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date-time"},"description":"ISO 8601 datetime — return only records after this date","example":"2026-01-01T00:00:00Z"}],"responses":{"200":{"description":"Historical records","content":{"application/json":{"schema":{"type":"object","properties":{"targetUrl":{"type":"string"},"count":{"type":"integer"},"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"capturedAt":{"type":"string","format":"date-time"},"extractedJson":{"type":"object"},"semanticContext":{"type":"object"}}}}}}}}},"400":{"description":"Missing or invalid targetUrl"},"401":{"description":"Unauthorized"}}}},"/v1/aste":{"get":{"summary":"Italian public auction scraper","description":"Specialized endpoint for Italian judicial auctions (aste giudiziarie). Returns a standardized JSON with all relevant fields: lot number, base price, minimum bid, deadline, court, address, category, surface area. Compatible with PVP, portaleaste.it, astegiudiziarie.eu and most Italian auction portals.","operationId":"fetchAsta","parameters":[{"name":"target","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"URL of the auction listing page","example":"https://www.portaleaste.com/aste/123456"}],"responses":{"200":{"description":"Auction data","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string","enum":["cache","live"]},"data":{"type":"object","properties":{"numero_lotto":{"type":"string","nullable":true},"prezzo_base":{"type":"number","nullable":true},"offerta_minima":{"type":"number","nullable":true},"rialzo_minimo":{"type":"number","nullable":true},"scadenza":{"type":"string","format":"date-time","nullable":true},"tribunale":{"type":"string","nullable":true},"indirizzo":{"type":"string","nullable":true},"comune":{"type":"string","nullable":true},"provincia":{"type":"string","nullable":true},"categoria":{"type":"string","nullable":true},"superficie_mq":{"type":"number","nullable":true}}}}}}}},"400":{"description":"Missing or invalid target"},"401":{"description":"Unauthorized"},"502":{"description":"Target site unreachable"}}}}},"components":{"securitySchemes":{"rapidApiKey":{"type":"apiKey","in":"header","name":"X-RapidAPI-Key"}}}}