{"openapi":"3.1.0","info":{"title":"SearchOps API","description":"Technical SEO Monitoring Platform API","version":"0.6.0","contact":{"email":"support@platphormnews.com"}},"servers":[{"url":"https://searchops.platphormnews.com/api","description":"Production server"}],"paths":{"/health":{"get":{"summary":"Health check","description":"Returns service health status","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"status":{"type":"string","enum":["healthy","degraded"]},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"/sites":{"get":{"summary":"List sites","description":"Get all monitored sites","responses":{"200":{"description":"List of sites","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Site"}}}}}}}}}},"/dashboard":{"get":{"summary":"Dashboard stats","description":"Get dashboard statistics for a site","parameters":[{"name":"siteId","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Dashboard statistics"}}}},"/crawl":{"post":{"summary":"Start crawl","description":"Start a new crawl run for a site","security":[{"PlatformApiKey":[]},{"PlatformBearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["siteId"],"properties":{"siteId":{"type":"string","format":"uuid"},"maxUrls":{"type":"integer","default":100},"maxDepth":{"type":"integer","minimum":0,"maximum":5,"default":3}}}}}},"responses":{"200":{"description":"Crawl completed successfully"}}}},"/v1/target/quality":{"get":{"summary":"Measure target search and semantic quality","description":"Read-only bounded measurement of response speed, semantic legibility, locale, i18n, canonical, and search metadata signals.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Observed target quality","content":{"application/json":{"schema":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["score","checks","tests"],"properties":{"score":{"type":["integer","null"],"minimum":0,"maximum":100},"checks":{"type":"object","additionalProperties":true},"tests":{"type":"array","items":{"$ref":"#/components/schemas/TargetQualityTest"}}},"additionalProperties":true}},"additionalProperties":false}}}},"422":{"description":"Target unavailable or rejected"}}}},"/v1/target/discoverability":{"get":{"summary":"Measure internal and provider-backed external discoverability","description":"Runs bounded brand, developer, API, documentation, MCP, and official queries through a configured provider adapter, plus authoritative Wikipedia, Wikidata, GitHub, npm, and PyPI entity adapters. Registry occurrence is evidence, not legitimacy; returns unable_to_verify when a provider is unavailable.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Observed or unable-to-verify discoverability evidence"},"422":{"description":"Target unavailable or rejected"}}}},"/urls":{"get":{"summary":"List URLs","description":"Get crawled URLs with filtering and pagination","parameters":[{"name":"siteId","in":"query","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","default":1}},{"name":"pageSize","in":"query","schema":{"type":"integer","default":20}},{"name":"label","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List of crawled URLs"}}}},"/alerts":{"get":{"summary":"List alerts","description":"Get alerts for a site","parameters":[{"name":"siteId","in":"query","required":true,"schema":{"type":"string"}},{"name":"isResolved","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"List of alerts"}}}},"/alerts/{id}/resolve":{"post":{"summary":"Resolve alert","description":"Mark an alert as resolved","security":[{"PlatformApiKey":[]},{"PlatformBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Alert resolved"}}}},"/mcp":{"get":{"summary":"Describe the SearchOps MCP server","responses":{"200":{"description":"MCP metadata and real registry state"}}},"post":{"summary":"Execute JSON-RPC 2.0 MCP requests","description":"Public read-only tools expose monitored sites and evidence-backed dashboards.","responses":{"200":{"description":"JSON-RPC result or error"}}}},"/gsc/import":{"post":{"summary":"Import GSC data","description":"Import Google Search Console CSV data","security":[{"PlatformApiKey":[]},{"PlatformBearer":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["siteId","csvData"],"properties":{"siteId":{"type":"string"},"csvData":{"type":"string"}}}}}},"responses":{"200":{"description":"Import successful"}}}}},"components":{"securitySchemes":{"PlatformApiKey":{"type":"apiKey","in":"header","name":"X-PlatPhorm-API-Key","description":"Use PLATPHORM_API_KEY for protected SearchOps actions."},"PlatformBearer":{"type":"http","scheme":"bearer","description":"Use Authorization: Bearer $PLATPHORM_API_KEY for protected SearchOps actions."}},"schemas":{"TargetQualityTest":{"type":"object","required":["id","title","status","detail","sourceUrl","method","evidence","parsed","response","confidence"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["pass","warn","fail","not_applicable","unable_to_verify","informational"]},"detail":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"method":{"type":"string"},"evidence":{"type":"string"},"parsed":{"type":"object","additionalProperties":true},"response":{"type":"object","required":["status","contentType"],"properties":{"status":{"type":"integer"},"contentType":{"type":["string","null"]}},"additionalProperties":false},"confidence":{"type":"string","enum":["high","medium","low"]},"failureOwner":{"type":"string","enum":["target","scanner","external-provider","credential-required","network","unknown"]},"remediation":{"type":"string"}},"additionalProperties":false},"Site":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"domain":{"type":"string"},"is_active":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}},"UrlLabel":{"type":"string","enum":["index","noindex","redirect","fix","delete","needs-content"]},"AlertSeverity":{"type":"string","enum":["critical","warning","info"]}}}}