{"openapi":"3.1.0","info":{"title":"Getspotted API","version":"1.0.0","description":"Find the sources AI engines (ChatGPT, Claude, Perplexity, Gemini) and Google cite for a query, per country, and the contacts behind them. Other tools track rankings — Getspotted finds the sources AI trusts.","contact":{"name":"Getspotted","url":"https://getspotted.ai"}},"servers":[{"url":"https://getspotted.ai","description":"Production"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"gsp_live_…","description":"API key created in your Getspotted dashboard."}},"schemas":{"Error":{"type":"object","required":["success","error","code"],"properties":{"success":{"type":"boolean","enum":[false]},"error":{"type":"string"},"code":{"type":"string"}}},"CitedSource":{"type":"object","properties":{"url":{"type":"string"},"domain":{"type":"string"},"title":{"type":"string"},"snippet":{"type":"string"},"score":{"type":"number"},"recommendationLevel":{"type":"string","enum":["PREMIUM","HIGH","MEDIUM","LOW"]},"engines":{"type":"array","items":{"type":"string"}},"positions":{"type":"object","additionalProperties":{"type":"integer"}},"crossEngine":{"type":"boolean"}}},"SearchResult":{"type":"object","properties":{"keyword":{"type":"string"},"locationCode":{"type":"string"},"country":{"type":"string"},"locale":{"type":"string"},"enginesQueried":{"type":"array","items":{"type":"string"}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/CitedSource"}},"hotspots":{"type":"array","items":{"$ref":"#/components/schemas/CitedSource"}},"crossMatchCount":{"type":"integer"},"tookMs":{"type":"integer"}}}}},"paths":{"/api/v1/search":{"post":{"summary":"Find AI-cited sources for a query","description":"Runs the query across Google + ChatGPT (+ AI Overview + Perplexity/Claude/Gemini) and returns the cited sources, scored, with per-engine positions. Costs 10 credits.","operationId":"search","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":2,"maxLength":200},"country":{"type":"string","description":"ISO-3166 alpha-2 market. Default US."},"ranking_filter":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Cited sources","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"data":{"$ref":"#/components/schemas/SearchResult"}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing/invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Insufficient credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts":{"post":{"summary":"Find editor contacts for a source domain","description":"Returns contact emails for a cited source domain. Costs 2 credits.","operationId":"contacts","security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"}}}}}},"responses":{"200":{"description":"Domain contacts"},"401":{"description":"Missing/invalid API key"},"402":{"description":"Insufficient credits"},"404":{"description":"No contacts found"}}}},"/api/v1/engines":{"get":{"summary":"List supported AI engines","operationId":"listEngines","security":[],"responses":{"200":{"description":"Engine registry"}}}},"/api/v1/countries":{"get":{"summary":"List supported markets","operationId":"listCountries","security":[],"responses":{"200":{"description":"Country list + AI Overview availability"}}}},"/api/v1/usage":{"get":{"summary":"Get this key's usage + credit balance","operationId":"usage","security":[{"apiKey":[]}],"responses":{"200":{"description":"Usage + balance"},"401":{"description":"Missing/invalid API key"}}}}}}