{"openapi":"3.1.0","info":{"title":"VeritasLinks VeritasScore Public + Agent API","version":"1.1.0","description":"Read-only public VeritasScore lookups by website domain, plus an authenticated Agent API (register, start analysis, poll, report). MCP endpoint available at \/mcp. Agents never pay via API: plan or quota walls return 402 with an upgrade_url for a human."},"servers":[{"url":"https:\/\/veritaslinks.com"}],"paths":{"\/score\/{domain}":{"get":{"summary":"Get VeritasScore for a domain (HTML by default)","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"amazon.com"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"rated or not_rated payload (when format=json) or HTML\/Markdown","content":{"application\/json":{"schema":{"oneOf":[{"$ref":"#\/components\/schemas\/RatedScore"},{"$ref":"#\/components\/schemas\/NotRated"}]}}}},"404":{"description":"invalid_domain","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/InvalidDomain"}}}}}}},"\/score\/{domain}.json":{"get":{"summary":"JSON VeritasScore for a domain","responses":{"200":{"description":"rated or not_rated JSON"},"404":{"description":"invalid_domain"}}}},"\/score\/{domain}.md":{"get":{"summary":"Markdown VeritasScore for a domain","responses":{"200":{"description":"Markdown document"},"404":{"description":"invalid_domain"}}}},"\/api\/agent\/v1\/register":{"post":{"summary":"Create an account and receive an API key (shown once)","description":"No API key needed. No captcha. Rate-limited per IP (default 5\/hour). Email verification follows the same rules as the website.","security":[],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RegisterRequest"}}}},"responses":{"201":{"description":"Account created","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/RegisterResponse"}}}},"422":{"description":"Validation failed","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"429":{"description":"Rate limited (Retry-After header)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}}}}},"\/api\/agent\/v1\/analyses":{"post":{"summary":"Start an analysis (idempotent per account + domain while queued\/running)","description":"Uses the same free-tier entitlement as the website \/start flow. Never charges money. Provide url or domain.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/StartAnalysisRequest"}}}},"responses":{"200":{"description":"Existing queued\/running analysis for this domain (idempotent replay)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Analysis"}}}},"202":{"description":"Analysis accepted; poll it (Retry-After \/ Location headers)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Analysis"}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"402":{"description":"Plan or quota required; body includes upgrade_url for a human","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"422":{"description":"Invalid url\/domain","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"429":{"description":"Daily analysis limit reached (Retry-After header)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}}}}},"\/api\/agent\/v1\/analyses\/{id}":{"get":{"summary":"Poll an analysis you started","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status. While queued\/running, Retry-After and poll_interval_seconds say how long to wait.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Analysis"}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"404":{"description":"Not found (own analyses only)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}}}}},"\/api\/agent\/v1\/reports\/{id}":{"get":{"summary":"Tier-filtered report for a completed analysis","description":"Free accounts receive the free preview plus locked-section descriptors; entitled accounts receive the full report.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"report_id from the analysis status (or the analysis id)","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Report payload","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Report"}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"404":{"description":"Not found (own reports only)","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"409":{"description":"Report not ready yet; keep polling the analysis","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}}}}},"\/api\/agent\/v1\/scores\/{domain}":{"get":{"summary":"Public VeritasScore (free preview) for a domain","description":"Same data as \/score\/{domain}.json, enriched with access.locked and next actions.","security":[{"bearerAuth":[]}],"parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string","example":"amazon.com"}}],"responses":{"200":{"description":"rated or not_rated payload","content":{"application\/json":{"schema":{"oneOf":[{"$ref":"#\/components\/schemas\/RatedScore"},{"$ref":"#\/components\/schemas\/NotRated"}]}}}},"401":{"description":"Missing or invalid API key","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}},"422":{"description":"invalid_domain","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/AgentError"}}}}}}},"\/catalog.json":{"get":{"summary":"VeritasScore catalog index as JSON","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","named","recent","name"]}},{"name":"range","in":"query","schema":{"type":"string","enum":["700","600","below600"]}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Catalog page","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CatalogPage"}}}}}}},"\/catalog\/{service}.json":{"get":{"summary":"VeritasScore catalog service page as JSON","parameters":[{"name":"service","in":"path","required":true,"schema":{"type":"string"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["score","named","recent","name"]}},{"name":"range","in":"query","schema":{"type":"string","enum":["700","600","below600"]}},{"name":"page","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Catalog service page","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CatalogPage"}}}},"404":{"description":"Unknown or private service"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Agent API key from POST \/api\/agent\/v1\/register or Profile \u2192 Agent API keys"}},"schemas":{"AgentError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"subscription_required"},"message":{"type":"string"},"action":{"$ref":"#\/components\/schemas\/AgentAction"},"upgrade_url":{"type":"string","description":"Only on 402: a human opens this to choose a plan"},"retry_after_seconds":{"type":"integer","description":"Only on 429"},"errors":{"type":"object","description":"Only on 422: field \u2192 messages"}}},"AgentAction":{"type":"object","properties":{"name":{"type":"string"},"method":{"type":"string"},"url":{"type":"string"},"description":{"type":"string"}}},"RegisterRequest":{"type":"object","required":["name","email","password","password_confirmation"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"password":{"type":"string","minLength":8},"password_confirmation":{"type":"string"}}},"RegisterResponse":{"type":"object","properties":{"user_id":{"type":"integer"},"email":{"type":"string"},"email_verified":{"type":"boolean"},"api_key":{"type":"string","description":"Shown once. Send as Authorization: Bearer <api_key>"},"message":{"type":"string"},"actions":{"type":"array","items":{"$ref":"#\/components\/schemas\/AgentAction"}}}},"StartAnalysisRequest":{"type":"object","description":"Provide url or domain","properties":{"url":{"type":"string","example":"https:\/\/example.com"},"domain":{"type":"string","example":"example.com"}}},"Analysis":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued","running","completed","failed"]},"domain":{"type":"string"},"url":{"type":"string"},"stage":{"type":["string","null"]},"progress_percent":{"type":["integer","null"]},"poll_url":{"type":"string"},"poll_interval_seconds":{"type":"integer"},"report_id":{"type":["string","null"],"description":"Set when status is completed"},"report_url":{"type":["string","null"]},"idempotent_replay":{"type":"boolean"},"tier":{"type":"string","enum":["free","full"]},"upgrade_url":{"type":"string"},"error":{"type":"string"}}},"Report":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"analysis_id":{"type":["string","null"]},"domain":{"type":"string"},"veritas_score":{"type":["integer","null"]},"tier":{"type":"string","enum":["free","full"]},"entitled":{"type":"boolean"},"report":{"type":"object","description":"Report V3 view model filtered to the account tier; report.access.locked lists locked sections for free accounts"},"links":{"type":"object"},"upgrade_url":{"type":"string"}}},"RatedScore":{"type":"object","required":["schema_version","status","domain","veritas_score","cite_as"],"properties":{"schema_version":{"type":"string","example":"1.0"},"status":{"type":"string","enum":["rated"]},"domain":{"type":"string"},"veritas_score":{"type":"integer"},"band":{"type":"string"},"cite_as":{"type":"string"}}},"NotRated":{"type":"object","required":["schema_version","status","domain"],"properties":{"schema_version":{"type":"string"},"status":{"type":"string","enum":["not_rated"]},"domain":{"type":"string"},"run_your_own_url":{"type":"string"},"page_url":{"type":"string"}}},"CatalogPage":{"type":"object","required":["catalog","companies","services","links","actions","note"],"properties":{"catalog":{"type":"object"},"companies":{"type":"array"},"services":{"type":"array"},"links":{"type":"object"},"actions":{"type":"object"},"note":{"type":"string"}}},"InvalidDomain":{"type":"object","properties":{"schema_version":{"type":"string"},"status":{"type":"string","enum":["invalid_domain"]},"domain":{"type":"string","nullable":true}}}}},"x-mcp-endpoint":"\/mcp"}