{"openapi":"3.1.0","info":{"title":"Vaneform API","version":"1.2.0","description":"Read cached website intelligence through HTTP or MCP. Domain snapshots are cache-only; keyword, bulk and TLD calls use the same product signals as Vaneform. Every estimate keeps as_of and confidence. The human guide is available at /docs/api."},"externalDocs":{"description":"Human API, MCP and agent documentation","url":"https://vaneform.com/docs/api"},"servers":[{"url":"https://vaneform.com/api/v1"}],"tags":[{"name":"Domain","description":"Cached snapshot for one domain."},{"name":"Keyword","description":"US/EN keyword brief. Pro-only."},{"name":"Compare","description":"Bulk and TLD compare. Scale plus registry."},{"name":"Account","description":"Plan and remaining lookups. Does not consume quota."}],"security":[{"bearerAuth":[]}],"paths":{"/domains/{domain}":{"get":{"operationId":"lookupDomain","tags":["Domain"],"summary":"Read a cached domain snapshot","parameters":[{"name":"domain","in":"path","required":true,"description":"A public registrable domain or host, such as google.com.","schema":{"type":"string","example":"google.com"}},{"name":"include","in":"query","required":false,"description":"Comma-separated families. Default is scale,registry,profile,popularity. Add search for the Pro search footprint cache.","schema":{"type":"string","example":"scale,registry,profile,popularity"}}],"responses":{"200":{"description":"Cached snapshot or an honest missing status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResource"},"example":{"domain":"example.com","status":"ready","refresh_policy":"cache_only","scale":{"status":"ready","estimate":"site","visits":7560000,"visits_mom_change_pct":15.06,"as_of":"2026-08-31","confidence":"medium"},"report_url":"https://vaneform.com/e/example-com"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"400":{"description":"Provide a valid domain, such as google.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"403":{"description":"Search footprint is a Pro include.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/domains/{domain}/scale":{"get":{"operationId":"getDomainScale","tags":["Domain"],"summary":"Read the cached full-site scale estimate","parameters":[{"name":"domain","in":"path","required":true,"description":"A public registrable domain or host, such as google.com.","schema":{"type":"string","example":"google.com"}}],"responses":{"200":{"description":"DomainResource containing the Scale family.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/domains/{domain}/registry":{"get":{"operationId":"getDomainRegistry","tags":["Domain"],"summary":"Read cached domain registration facts","parameters":[{"name":"domain","in":"path","required":true,"description":"A public registrable domain or host, such as google.com.","schema":{"type":"string","example":"google.com"}}],"responses":{"200":{"description":"DomainResource containing the Registry family.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/domains/{domain}/profile":{"get":{"operationId":"getDomainProfile","tags":["Domain"],"summary":"Read cached public site profile facts","parameters":[{"name":"domain","in":"path","required":true,"description":"A public registrable domain or host, such as google.com.","schema":{"type":"string","example":"google.com"}}],"responses":{"200":{"description":"DomainResource containing the Profile family.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/domains/{domain}/popularity":{"get":{"operationId":"getDomainPopularity","tags":["Domain"],"summary":"Read cached public rank facts","parameters":[{"name":"domain","in":"path","required":true,"description":"A public registrable domain or host, such as google.com.","schema":{"type":"string","example":"google.com"}}],"responses":{"200":{"description":"DomainResource containing the Popularity family.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/domains/{domain}/search":{"get":{"operationId":"getDomainSearch","tags":["Domain"],"summary":"Read the cached Pro search footprint","parameters":[{"name":"domain","in":"path","required":true,"description":"A public registrable domain or host, such as google.com.","schema":{"type":"string","example":"google.com"}}],"responses":{"200":{"description":"DomainResource containing the Search family.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DomainResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"403":{"description":"Search footprint is a Pro include.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/keyword":{"get":{"operationId":"lookupKeyword","tags":["Keyword"],"summary":"Read keyword demand and Google occupancy","parameters":[{"name":"q","in":"query","required":true,"description":"Keyword such as ai or website traffic checker.","schema":{"type":"string","example":"ai"}}],"responses":{"200":{"description":"Cached brief, or a Pro miss that buys and stores this month.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeywordResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"400":{"description":"Request is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"403":{"description":"This call is a Pro capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/bulk":{"get":{"operationId":"compareBulk","tags":["Compare"],"summary":"Compare domains side by side","parameters":[{"name":"q","in":"query","required":true,"description":"Comma-separated domains, such as google.com,apple.com.","schema":{"type":"string","example":"google.com,apple.com"}}],"responses":{"200":{"description":"Scale and registry for each domain. One daily lookup per domain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"400":{"description":"Request is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/tld":{"get":{"operationId":"compareTld","tags":["Compare"],"summary":"Compare the same name across suffixes","parameters":[{"name":"q","in":"query","required":true,"description":"Registrable base name, such as google.","schema":{"type":"string","example":"google"}},{"name":"s","in":"query","required":false,"description":"Optional comma-separated suffixes. Default is com,ai,io.","schema":{"type":"string","example":"com,ai,io"}}],"responses":{"200":{"description":"Same row shape as /bulk. Count follows the compare limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"400":{"description":"Request is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}},"/account":{"get":{"operationId":"getAccount","tags":["Account"],"summary":"Read plan and remaining usage","responses":{"200":{"description":"Quota ledger. Does not consume a lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResource"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"401":{"description":"Missing or invalid bearer key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"429":{"description":"Daily quota, pace or concurrency limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}},"500":{"description":"Unexpected server failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Request-Id":{"description":"Stable id for this request, useful when contacting support.","schema":{"type":"string"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"vf_live_…","description":"Send a vf_live_ key in Authorization. Query-string credentials are rejected."}},"schemas":{"DomainResource":{"type":"object","required":["domain","status","refresh_policy"],"properties":{"domain":{"type":"string"},"status":{"type":"string","enum":["ready","partial","missing","error"]},"refresh_policy":{"type":"string","const":"cache_only"},"scale":{"$ref":"#/components/schemas/ScaleResource"},"registry":{"$ref":"#/components/schemas/RegistryResource"},"profile":{"$ref":"#/components/schemas/ProfileResource"},"popularity":{"$ref":"#/components/schemas/PopularityResource"},"search":{"$ref":"#/components/schemas/SearchResource"},"report_url":{"type":"string","format":"uri"}}},"ScaleResource":{"type":"object","properties":{"status":{"type":"string","enum":["ready","partial","missing","error"]},"title":{"type":"string"},"description":{"type":"string"},"month":{"type":"string","pattern":"^\\d{4}-\\d{2}$"},"as_of":{"type":"string"},"confidence":{"type":"string","enum":["low","medium","high"]},"estimate":{"type":"string","enum":["site","search"]},"visits":{"type":["number","null"]},"visits_mom_change_pct":{"type":["number","null"]},"global_rank":{"type":["integer","null"]},"country_rank":{"type":"object","properties":{"country":{"type":"string"},"rank":{"type":"integer"}}},"bounce_rate":{"type":["number","null"],"description":"Ratio from 0 to 1."},"pages_per_visit":{"type":["number","null"]},"time_on_site_seconds":{"type":["number","null"]},"category":{"type":"string"},"category_rank":{"type":["integer","null"]},"monthly_visits":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"visits":{"type":"number"}}}},"sources":{"type":"object","additionalProperties":{"type":"number","minimum":0,"maximum":1}},"top_regions":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"share":{"type":"number","minimum":0,"maximum":1}}}},"top_keywords":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"search_volume_monthly":{"type":"number"},"estimated_visits":{"type":"number"}}}}}},"RegistryResource":{"type":"object","properties":{"status":{"type":"string"},"created_at":{"type":"string"},"expires_at":{"type":"string"},"updated_at":{"type":"string"},"registrar":{"type":"string"},"name_servers":{"type":"array","items":{"type":"string"}},"statuses":{"type":"array","items":{"type":"string"}},"dnssec":{"type":["boolean","null"]},"age_days":{"type":["integer","null"]},"as_of":{"type":"string"}}},"ProfileResource":{"type":"object","description":"Public site, DNS, hosting, email and TLS facts. Fields are omitted when unavailable.","additionalProperties":true,"properties":{"status":{"type":"string"},"requested_url":{"type":"string","format":"uri"},"final_url":{"type":"string","format":"uri"},"http_status":{"type":"integer"},"as_of":{"type":"string"},"confidence":{"type":"string"}}},"PopularityResource":{"type":"object","properties":{"status":{"type":"string"},"link_rank":{"type":["integer","null"]},"tld":{"type":"string"},"tld_rank":{"type":["integer","null"]},"referring_ips":{"type":["integer","null"]},"referring_subnets":{"type":["integer","null"]},"rank_change":{"type":["integer","null"]},"board_rank":{"type":["integer","null"]},"as_of":{"type":"string"},"confidence":{"type":"string"}}},"SearchResource":{"type":"object","description":"This month's Pro search footprint. Search and site visits are separate estimates.","properties":{"status":{"type":"string"},"as_of":{"type":"string"},"confidence":{"type":"string"},"market":{"type":"object"},"include_subdomains":{"type":"boolean"},"organic_etv":{"type":["number","null"]},"keyword_count":{"type":["integer","null"]},"page_count":{"type":["integer","null"]},"competitor_count":{"type":["integer","null"]},"competitors_pending":{"type":"boolean"},"ai_overview_count":{"type":["integer","null"]},"keywords":{"type":"array","items":{"type":"object"}},"pages":{"type":"array","items":{"type":"object"}},"competitors":{"type":"array","items":{"type":"object"}}}},"KeywordResource":{"type":"object","properties":{"keyword":{"type":"string"},"market":{"type":"object"},"status":{"type":"string"},"as_of":{"type":"string"},"search_volume_monthly":{"type":["number","null"]},"cpc_usd":{"type":["number","null"]},"keyword_difficulty":{"type":["number","null"]},"search_intent":{"type":"string"},"items":{"type":"array","items":{"type":"object"}}}},"CompareResource":{"type":"object","required":["q","count","items"],"properties":{"q":{"type":"string"},"suffixes":{"type":"array","items":{"type":"string"}},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/CompareItem"}}}},"CompareItem":{"type":"object","properties":{"domain":{"type":"string"},"title":{"type":"string"},"scale":{"$ref":"#/components/schemas/ScaleResource"},"registry":{"$ref":"#/components/schemas/RegistryResource"},"report_url":{"type":"string","format":"uri"}}},"AccountResource":{"type":"object","properties":{"plan":{"type":"string"},"access_tier":{"type":"string"},"lookup":{"$ref":"#/components/schemas/QuotaResource"},"search":{"$ref":"#/components/schemas/QuotaResource"}}},"QuotaResource":{"type":"object","required":["used","limit","remaining","resets_at"],"properties":{"used":{"type":"integer"},"limit":{"type":"integer"},"remaining":{"type":"integer"},"resets_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","status","request_id","docs_url"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_domain","unauthorized","invalid_api_key","lookup_limit_exceeded","lookup_rate_exceeded","search_requires_pro","pro_required","not_found","method_not_allowed","internal_error"]},"message":{"type":"string"},"status":{"type":"integer"},"request_id":{"type":"string"},"docs_url":{"type":"string","format":"uri"}}}}}}},"x-error-codes":{"invalid_request":{"status":400,"message":"Request is malformed."},"invalid_domain":{"status":400,"message":"Provide a valid domain, such as google.com."},"unauthorized":{"status":401,"message":"Missing or malformed API key. Send it as `Authorization: Bearer vf_live_...`."},"invalid_api_key":{"status":401,"message":"Invalid API key."},"lookup_limit_exceeded":{"status":429,"message":"Daily lookup quota has been used up."},"lookup_rate_exceeded":{"status":429,"message":"Too many lookups in a short window. Retry later or upgrade to Pro."},"search_requires_pro":{"status":403,"message":"Search footprint is a Pro include."},"pro_required":{"status":403,"message":"This call is a Pro capability."},"not_found":{"status":404,"message":"Unknown route."},"method_not_allowed":{"status":405,"message":"This method is not allowed for this route."},"internal_error":{"status":500,"message":"Unexpected server error."}}}