{"openapi":"3.1.0","info":{"title":"Ferrule Google Search Console API","version":"1.0.0","description":"REST API for Google Search Console via the Ferrule gateway.","contact":{"name":"Ferrule","url":"https://ferrule.io"}},"servers":[{"url":"https://0.0.0.0:3000","description":"Ferrule gateway"}],"paths":{"/api/v1/google-searchconsole/sites":{"get":{"operationId":"google-searchconsole.list_sites","description":"List all Search Console sites (properties) the authenticated user has access to.","tags":["google-searchconsole"],"security":[{"oauth2":[]},{"bearerApiKey":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"siteEntry":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"siteUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"permissionLevel":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":{}}},{"type":"null"}]}},"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}}}}},"/api/v1/google-searchconsole/sites/{siteUrl}":{"get":{"operationId":"google-searchconsole.get_site","description":"Get information about a specific Search Console site (property).","tags":["google-searchconsole"],"security":[{"oauth2":[]},{"bearerApiKey":[]}],"parameters":[{"in":"path","name":"siteUrl","schema":{"type":"string","description":"The URL of the site to retrieve. For domain properties use 'sc-domain:example.com'. For URL-prefix properties use the full URL including protocol."},"required":true,"description":"The URL of the site to retrieve. For domain properties use 'sc-domain:example.com'. For URL-prefix properties use the full URL including protocol."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"siteUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"permissionLevel":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}}}}},"/api/v1/google-searchconsole/sites/{siteUrl}/search-analytics/query":{"post":{"operationId":"google-searchconsole.query_search_analytics","description":"Query search traffic data for a site. Returns clicks, impressions, CTR, and position data. Supports filtering by dimensions (query, page, country, device, searchAppearance, date), date ranges, and more.","tags":["google-searchconsole"],"security":[{"oauth2":[]},{"bearerApiKey":[]}],"parameters":[{"in":"path","name":"siteUrl","schema":{"type":"string","description":"The URL of the site to query. For domain properties use 'sc-domain:example.com'."},"required":true,"description":"The URL of the site to query. For domain properties use 'sc-domain:example.com'."},{"in":"query","name":"startDate","schema":{"type":"string","description":"Start date in YYYY-MM-DD format (required)."}},{"in":"query","name":"endDate","schema":{"type":"string","description":"End date in YYYY-MM-DD format (required)."}},{"in":"query","name":"dimensions","schema":{"description":"Dimensions to group by: query, page, country, device, searchAppearance, date.","type":"array","items":{"type":"string"}}},{"in":"query","name":"type","schema":{"description":"Search type filter: web, image, video, news, discover, googleNews.","type":"string"}},{"in":"query","name":"rowLimit","schema":{"description":"Maximum number of rows to return (default 1000, max 25000).","type":"number"}},{"in":"query","name":"startRow","schema":{"description":"Zero-based index of the first row to return.","type":"number"}},{"in":"query","name":"dimensionFilterGroups","schema":{"description":"Array of dimension filter groups. Each group has a groupType and filters array.","type":"array","items":{}}},{"in":"query","name":"aggregationType","schema":{"description":"How data is aggregated: auto, byPage, or byProperty.","type":"string"}},{"in":"query","name":"dataState","schema":{"description":"Data freshness: final (default) or all (includes fresh/partial data).","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Request body parameters"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"clicks":{"anyOf":[{"type":"number"},{"type":"null"}]},"ctr":{"anyOf":[{"type":"number"},{"type":"null"}]},"impressions":{"anyOf":[{"type":"number"},{"type":"null"}]},"keys":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"position":{"anyOf":[{"type":"number"},{"type":"null"}]}},"additionalProperties":{}}},{"type":"null"}]},"responseAggregationType":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}}}}},"/api/v1/google-searchconsole/sites/{siteUrl}/sitemaps":{"get":{"operationId":"google-searchconsole.list_sitemaps","description":"List the sitemaps submitted for a site.","tags":["google-searchconsole"],"security":[{"oauth2":[]},{"bearerApiKey":[]}],"parameters":[{"in":"path","name":"siteUrl","schema":{"type":"string","description":"The URL of the site. For domain properties use 'sc-domain:example.com'."},"required":true,"description":"The URL of the site. For domain properties use 'sc-domain:example.com'."},{"in":"query","name":"sitemapIndex","schema":{"description":"A URL of a sitemap index file to filter results to sitemaps referenced by that index.","type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"sitemap":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"path":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSubmitted":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastDownloaded":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPending":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"isSitemapsIndex":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"warnings":{"anyOf":[{"type":"string"},{"type":"null"}]},"errors":{"anyOf":[{"type":"string"},{"type":"null"}]},"contents":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"submitted":{"anyOf":[{"type":"string"},{"type":"null"}]},"indexed":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":{}}},{"type":"null"}]}},"additionalProperties":{}}},{"type":"null"}]}},"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}}}}},"/api/v1/google-searchconsole/sites/{siteUrl}/sitemaps/{feedpath}":{"get":{"operationId":"google-searchconsole.get_sitemap","description":"Get information about a specific sitemap.","tags":["google-searchconsole"],"security":[{"oauth2":[]},{"bearerApiKey":[]}],"parameters":[{"in":"path","name":"siteUrl","schema":{"type":"string","description":"The URL of the site. For domain properties use 'sc-domain:example.com'."},"required":true,"description":"The URL of the site. For domain properties use 'sc-domain:example.com'."},{"in":"path","name":"feedpath","schema":{"type":"string","description":"The URL of the sitemap to retrieve."},"required":true,"description":"The URL of the sitemap to retrieve."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"path":{"anyOf":[{"type":"string"},{"type":"null"}]},"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastSubmitted":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastDownloaded":{"anyOf":[{"type":"string"},{"type":"null"}]},"isPending":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"isSitemapsIndex":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"warnings":{"anyOf":[{"type":"string"},{"type":"null"}]},"errors":{"anyOf":[{"type":"string"},{"type":"null"}]},"contents":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"type":{"anyOf":[{"type":"string"},{"type":"null"}]},"submitted":{"anyOf":[{"type":"string"},{"type":"null"}]},"indexed":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":{}}},{"type":"null"}]}},"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}}}}},"/api/v1/google-searchconsole/url-inspection/inspect":{"post":{"operationId":"google-searchconsole.inspect_url","description":"Inspect a URL to get its index status, AMP status, mobile usability, and rich results status. Requires the full URL and site URL.","tags":["google-searchconsole"],"security":[{"oauth2":[]},{"bearerApiKey":[]}],"parameters":[{"in":"query","name":"inspectionUrl","schema":{"type":"string","description":"The fully-qualified URL to inspect (required)."}},{"in":"query","name":"siteUrl","schema":{"type":"string","description":"The URL of the property as defined in Search Console. For domain properties use 'sc-domain:example.com' (required)."}},{"in":"query","name":"languageCode","schema":{"description":"IETF BCP-47 language code for translated issue messages.","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{},"description":"Request body parameters"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"inspectionResult":{"anyOf":[{"type":"object","properties":{"inspectionResultLink":{"anyOf":[{"type":"string"},{"type":"null"}]},"indexStatusResult":{"anyOf":[{"type":"object","properties":{"verdict":{"anyOf":[{"type":"string"},{"type":"null"}]},"coverageState":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsTxtState":{"anyOf":[{"type":"string"},{"type":"null"}]},"indexingState":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCrawlTime":{"anyOf":[{"type":"string"},{"type":"null"}]},"pageFetchState":{"anyOf":[{"type":"string"},{"type":"null"}]},"crawledAs":{"anyOf":[{"type":"string"},{"type":"null"}]},"referringUrls":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"additionalProperties":{}},{"type":"null"}]},"ampResult":{"anyOf":[{"type":"object","properties":{"verdict":{"anyOf":[{"type":"string"},{"type":"null"}]},"ampUrl":{"anyOf":[{"type":"string"},{"type":"null"}]},"robotsTxtState":{"anyOf":[{"type":"string"},{"type":"null"}]},"indexingState":{"anyOf":[{"type":"string"},{"type":"null"}]},"ampIndexStatusVerdict":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastCrawlTime":{"anyOf":[{"type":"string"},{"type":"null"}]},"pageFetchState":{"anyOf":[{"type":"string"},{"type":"null"}]},"issues":{"anyOf":[{"type":"array","items":{}},{"type":"null"}]}},"additionalProperties":{}},{"type":"null"}]},"mobileUsabilityResult":{"anyOf":[{"type":"object","properties":{"verdict":{"anyOf":[{"type":"string"},{"type":"null"}]},"issues":{"anyOf":[{"type":"array","items":{}},{"type":"null"}]}},"additionalProperties":{}},{"type":"null"}]},"richResultsResult":{"anyOf":[{"type":"object","properties":{"verdict":{"anyOf":[{"type":"string"},{"type":"null"}]},"detectedItems":{"anyOf":[{"type":"array","items":{}},{"type":"null"}]}},"additionalProperties":{}},{"type":"null"}]}},"additionalProperties":{}},{"type":"null"}]}},"additionalProperties":{}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}},"502":{"description":"Upstream error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"code":{"type":"string"},"message":{"type":"string"}},"required":["error","code","message"],"additionalProperties":false}}}}}}}},"webhooks":{},"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"/oauth/authorize","tokenUrl":"/oauth/token","scopes":{}}}},"bearerApiKey":{"type":"http","scheme":"bearer","description":"API key authentication. Pass a Ferrule API key as a Bearer token."}}}}