{"openapi":"3.1.0","info":{"title":"Searvia API","version":"1.0.0","description":"Rankings, AI visibility, site health, reviews, app metadata and market data of your Searvia account. The same tools as the Searvia MCP server, with the same plan limits, credits and account scope."},"servers":[{"url":"https://searvia.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings › API & MCP."}},"schemas":{"Meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"last_page":{"type":"integer"},"message":{"type":"string"},"credits_used":{"type":"integer"}}},"Result":{"type":"object","required":["data"],"properties":{"data":[],"meta":{"$ref":"#/components/schemas/Meta"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["status","code","message"],"properties":{"status":{"type":"integer"},"code":{"type":"string","enum":["bad_request","unauthenticated","payment_required","forbidden","not_found","validation_failed","rate_limited","server_error","unavailable"]},"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/account/usage":{"get":{"operationId":"getUsage","summary":"Plan, credits, quotas and this month's API and MCP calls.","tags":["Account"],"x-searvia-kind":"read","parameters":[],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"operationId":"listProjects","summary":"Projects (websites and apps) of the account.","tags":["Projects"],"x-searvia-kind":"read","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Result page; meta has page, per_page, total and last_page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}":{"get":{"operationId":"getProject","summary":"Overview of one project: rankings, visibility, reviews and open growth actions.","tags":["Projects"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"days","in":"query","schema":{"description":"Period length: 7, 30 or 90 (default 7).","type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/competitors":{"get":{"operationId":"listCompetitors","summary":"Tracked competitors of a project.","tags":["Projects"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/keywords":{"get":{"operationId":"listKeywords","summary":"Tracked keywords with current rank, 1 and 7 day change, popularity, difficulty and daily history.","tags":["Rankings"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"days","in":"query","schema":{"description":"Days of history to include (1-90, default 30).","type":"integer"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Result page; meta has page, per_page, total and last_page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addKeywords","summary":"Track keywords (within the plan quota; the first check runs right away).","tags":["Rankings"],"x-searvia-kind":"write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"description":"Keywords to track (max 200 keyword × country rows).","items":{"type":"string"},"type":"array"},"country":{"description":"Two-letter country code (default: the project's country).","type":"string"},"countries":{"description":"Several two-letter country codes: each keyword is tracked in each (overrides country).","items":{"type":"string"},"type":"array"},"language":{"description":"Language code for a single country (default: the project's language).","type":"string"},"source_keyword":{"description":"Tracked keyword these are local-language forms of (groups them on the global board).","type":"string"}},"required":["keywords"]}}}},"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"removeKeywords","summary":"Stop tracking keywords (by text or id).","tags":["Rankings"],"x-searvia-kind":"destroy","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"description":"Keyword texts to remove.","items":{"type":"string"},"type":"array"},"keyword_ids":{"description":"Keyword ids to remove (from get_keyword_rankings).","items":{"type":"integer"},"type":"array"},"country":{"description":"Only remove the keywords tracked in this two-letter country.","type":"string"}}}}}},"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/rankings/refresh":{"post":{"operationId":"refreshRankings","summary":"Check rankings now.","tags":["Rankings"],"x-searvia-kind":"write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"description":"Keyword texts to re-check (max 20).","items":{"type":"string"},"type":"array"},"keyword_ids":{"description":"Keyword ids to re-check (max 20).","items":{"type":"integer"},"type":"array"},"country":{"description":"Only keywords tracked in this two-letter country.","type":"string"}}}}}},"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/keywords/{keyword_id}/history":{"get":{"operationId":"getKeywordHistory","summary":"Daily rank history of one keyword with competitor ranks.","tags":["Rankings"],"x-searvia-kind":"read","parameters":[{"name":"keyword_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"project_id","in":"query","schema":{"description":"Project id from list_projects (with keyword).","type":"integer"}},{"name":"keyword","in":"query","schema":{"description":"Tracked keyword text (with project_id).","type":"string"}},{"name":"country","in":"query","schema":{"description":"Two-letter country code when the keyword is tracked in several countries.","type":"string"}},{"name":"days","in":"query","schema":{"description":"Days of history (1-365, default 90).","type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domain-analyses":{"get":{"operationId":"listDomainAnalyses","summary":"Domain analyses of the account.","tags":["Domains"],"x-searvia-kind":"read","parameters":[],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"analyzeDomain","summary":"Analyze a domain (uses credits): traffic, keywords, top pages, page types, competitors and backlinks.","tags":["Domains"],"x-searvia-kind":"spend","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"description":"analyze_domain: domain.","type":"string"},"country":{"description":"Country code.","type":"string"}}}}}},"parameters":[],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough credits or quota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/domain-analyses/{analysis_id}":{"get":{"operationId":"getDomainAnalysis","summary":"One domain analysis.","tags":["Domains"],"x-searvia-kind":"read","parameters":[{"name":"analysis_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/site-health":{"get":{"operationId":"getSiteHealth","summary":"Latest site audit, AI discoverability, security scan and page speed of a website project.","tags":["Site health"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/site-audits":{"post":{"operationId":"startSiteAudit","summary":"Start a site audit (at most once an hour).","tags":["Site health"],"x-searvia-kind":"write","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/site-audits/{audit_id}":{"get":{"operationId":"getSiteAudit","summary":"Issues and pages of one site audit.","tags":["Site health"],"x-searvia-kind":"read","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/backlinks":{"get":{"operationId":"getBacklinks","summary":"Backlink summary with new and lost links.","tags":["Site health"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/ai-visibility":{"get":{"operationId":"getAiVisibility","summary":"AI visibility summary, questions and latest answers of a project.","tags":["AI visibility"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/ai-visibility/questions":{"post":{"operationId":"addAiQuestions","summary":"Track AI questions (one per line in `prompts`).","tags":["AI visibility"],"x-searvia-kind":"write","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"prompts":{"description":"Questions, one per line.","type":"string"}}}}}},"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/ai-visibility/questions/{prompt_id}":{"get":{"operationId":"getAiQuestion","summary":"Timeline and answers of one AI question.","tags":["AI visibility"],"x-searvia-kind":"read","parameters":[{"name":"prompt_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"date","in":"query","schema":{"description":"get_question: YYYY-MM-DD answers to show.","type":"string"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/reviews":{"get":{"operationId":"listReviews","summary":"Store reviews of an app project.","tags":["Apps"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"max_rating","in":"query","schema":{"description":"Only reviews with this many stars or fewer (1-5).","type":"integer"}},{"name":"unanswered","in":"query","schema":{"description":"Only reviews without a developer reply.","type":"boolean"}},{"name":"limit","in":"query","schema":{"description":"1-100, default 25.","type":"integer"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Result page; meta has page, per_page, total and last_page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/metadata":{"get":{"operationId":"getAppMetadata","summary":"Store listing of an app project per language (including the App Store keyword field when connected).","tags":["Apps"],"x-searvia-kind":"read","parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"locale","in":"query","schema":{"description":"Store localization, e.g. en-US, tr, de-DE (optional; default the project language).","type":"string"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/apps/{app_id}":{"get":{"operationId":"getMarketApp","summary":"Estimated revenue, downloads and chart history of any App Store app.","tags":["Market"],"x-searvia-kind":"read","parameters":[{"name":"app_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"name","in":"query","schema":{"description":"App name (when no app_id); the best earning match is used.","type":"string"}},{"name":"window","in":"query","schema":{"description":"Period in days: 30 or 90 (default 30). Values are converted to monthly.","type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/top-earning":{"get":{"operationId":"listTopEarningApps","summary":"Top earning or fastest growing apps by country and category.","tags":["Market"],"x-searvia-kind":"read","parameters":[{"name":"country","in":"query","schema":{"description":"Two-letter country code of a scanned market, or ALL for all 25 (default ALL).","type":"string"}},{"name":"genre","in":"query","schema":{"description":"App Store genre id: 0 all, 6000 Business, 6001 Weather, 6002 Utilities, 6003 Travel, 6004 Sports, 6005 Social Networking, 6006 Reference, 6007 Productivity, 6008 Photo & Video, 6009 News, 6010 Navigation, 6011 Music, 6012 Lifestyle, 6013 Health & Fitness, 6014 Games, 6015 Finance, 6016 Entertainment, 6017 Education, 6018 Books, 6020 Medical, 6021 Magazines & Newspapers, 6023 Food & Drink, 6024 Shopping, 6026 Developer Tools, 6027 Graphics & Design, 7001 Action games, 7002 Adventure games, 7003 Casual games, 7004 Board games, 7005 Card games, 7006 Casino games, 7009 Family games, 7011 Music games, 7012 Puzzle games, 7013 Racing games, 7014 Role-playing games, 7015 Simulation games, 7016 Sports games, 7017 Strategy games, 7018 Trivia games, 7019 Word games.","type":"integer"}},{"name":"window","in":"query","schema":{"description":"Period in days: 30 or 90 (default 30). Values are converted to monthly.","type":"integer"}},{"name":"sort","in":"query","schema":{"description":"revenue (default), downloads, ratings or newest.","type":"string"}},{"name":"pricing","in":"query","schema":{"description":"all (default), free, paid, under5 or over5.","type":"string"}},{"name":"min_ratings","in":"query","schema":{"description":"Only apps with at least this many ratings: 100, 1000, 10000 or 100000.","type":"integer"}},{"name":"trend","in":"query","schema":{"description":"Instead of the top list, the fastest growing apps by revenue, downloads or ratings.","type":"string"}},{"name":"trend_days","in":"query","schema":{"description":"Growth period for trend: 7, 30 (default) or 90 days.","type":"integer"}},{"name":"limit","in":"query","schema":{"description":"Max apps (1-50, default 20).","type":"integer"}},{"name":"offset","in":"query","schema":{"description":"Skip this many apps (paging; use next_offset).","type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/market/new-winners":{"get":{"operationId":"listNewWinningApps","summary":"Recently released apps that already earn.","tags":["Market"],"x-searvia-kind":"read","parameters":[{"name":"country","in":"query","schema":{"description":"Two-letter country code of a scanned market, or ALL for all 25 (default ALL).","type":"string"}},{"name":"genre","in":"query","schema":{"description":"App Store genre id: 0 all, 6000 Business, 6001 Weather, 6002 Utilities, 6003 Travel, 6004 Sports, 6005 Social Networking, 6006 Reference, 6007 Productivity, 6008 Photo & Video, 6009 News, 6010 Navigation, 6011 Music, 6012 Lifestyle, 6013 Health & Fitness, 6014 Games, 6015 Finance, 6016 Entertainment, 6017 Education, 6018 Books, 6020 Medical, 6021 Magazines & Newspapers, 6023 Food & Drink, 6024 Shopping, 6026 Developer Tools, 6027 Graphics & Design, 7001 Action games, 7002 Adventure games, 7003 Casual games, 7004 Board games, 7005 Card games, 7006 Casino games, 7009 Family games, 7011 Music games, 7012 Puzzle games, 7013 Racing games, 7014 Role-playing games, 7015 Simulation games, 7016 Sports games, 7017 Strategy games, 7018 Trivia games, 7019 Word games.","type":"integer"}},{"name":"released_within_days","in":"query","schema":{"description":"Released in the last 30, 90, 180 or 365 days (default 90).","type":"integer"}},{"name":"window","in":"query","schema":{"description":"Revenue period in days: 30 or 90 (default 30). Values are converted to monthly.","type":"integer"}},{"name":"sort","in":"query","schema":{"description":"revenue (default), downloads, ratings or newest.","type":"string"}},{"name":"limit","in":"query","schema":{"description":"Max apps (1-50, default 20).","type":"integer"}}],"responses":{"200":{"description":"Result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/reports/rankings":{"get":{"operationId":"reportRankings","summary":"One row per keyword and day: rank, checked depth and competitor ranks.","tags":["Reports"],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"from","in":"query","description":"YYYY-MM-DD (default: 30 days ago).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"YYYY-MM-DD (default: today). At most 365 days.","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Result page; meta has page, per_page, total and last_page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/reports/ai-visibility":{"get":{"operationId":"reportAiVisibility","summary":"One row per AI answer: question, platform, mentioned, cited, source position and sentiment.","tags":["Reports"],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"from","in":"query","description":"YYYY-MM-DD (default: 30 days ago).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"YYYY-MM-DD (default: today). At most 365 days.","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Result page; meta has page, per_page, total and last_page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{project_id}/reports/site-health":{"get":{"operationId":"reportSiteHealth","summary":"One row per site audit: health score, AI discoverability score, errors, warnings and pages.","tags":["Reports"],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"from","in":"query","description":"YYYY-MM-DD (default: 30 days ago).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"YYYY-MM-DD (default: today). At most 365 days.","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Result page; meta has page, per_page, total and last_page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audit-logs":{"get":{"operationId":"listAuditLogs","summary":"Audit log of the account: every change and credit spend from the panel, MCP and the API (owners and admins).","tags":["Account"],"parameters":[{"name":"source","in":"query","schema":{"type":"string","enum":["panel","mcp","api"]}},{"name":"kind","in":"query","schema":{"type":"string","enum":["write","spend","destroy","publish"]}},{"name":"from","in":"query","description":"YYYY-MM-DD (default: 30 days ago).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"YYYY-MM-DD (default: today). At most 365 days.","schema":{"type":"string","format":"date"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Result page; meta has page, per_page, total and last_page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Result"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The plan has no API access, the key is read-only or the role does not allow it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found in this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid arguments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or monthly call limit reached; see Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}