{"openapi":"3.0.3","info":{"title":"AiVIS Cite Ledger API","version":"1.0.0","description":"AiVIS Cite Ledger REST API. Audit whether websites are machine-readable, structurally extractable, and citation-ready inside AI-generated answers.","contact":{"name":"AiVIS Cite Ledger Support","url":"https://aivis.biz","email":"support@aivis.biz"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.aivis.biz","description":"Production"}],"security":[{"apiKeyAuth":[]}],"tags":[{"name":"Audits","description":"AI visibility audit CRUD"},{"name":"Visibility Compiler","description":"Two-phase audit execution, evidence results, fixpack generation, and citation velocity tracking"},{"name":"Analytics","description":"Score history and platform analytics"},{"name":"Competitors","description":"Competitor tracking records"},{"name":"Evidence","description":"Evidence-linked audit payloads"},{"name":"Page Validation","description":"Technical page validation checks"},{"name":"Usage","description":"API metering and usage stats"},{"name":"Payments","description":"Billing and checkout payment operations"},{"name":"Compliance","description":"Consumer policy and consent management"}],"paths":{"/api/v1/audits":{"get":{"operationId":"listAudits","tags":["Audits"],"summary":"List audits with pagination","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"description":"Number of results per page"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Pagination offset"}],"responses":{"200":{"description":"Paginated list of audits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/audits/{id}":{"get":{"operationId":"getAudit","tags":["Audits"],"summary":"Get full audit payload by ID","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Audit ID"}],"responses":{"200":{"description":"Full audit with result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditDetailResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"},"404":{"description":"Audit not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/analytics":{"get":{"operationId":"getAnalytics","tags":["Analytics"],"summary":"Get score history grouped by URL","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":90},"description":"Lookback window in days"}],"responses":{"200":{"description":"Analytics data with score history and platform averages","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalyticsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"}}}},"/api/v1/competitors":{"get":{"operationId":"listCompetitors","tags":["Competitors"],"summary":"Get competitor tracking records","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Competitor list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"}}}},"/api/v1/evidence/{auditId}":{"get":{"operationId":"getEvidence","tags":["Evidence"],"summary":"Get evidence manifest and recommendation evidence for an audit","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"auditId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Audit ID"}],"responses":{"200":{"description":"Evidence payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Audit not found"}}}},"/api/v1/usage":{"get":{"operationId":"getUsage","tags":["Usage"],"summary":"Get current-month metered API usage","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"API usage snapshot for current billing month","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/page-validation":{"post":{"operationId":"runPageValidation","tags":["Page Validation"],"summary":"Run and store technical page validation","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Public URL to validate"}}}}}},"responses":{"201":{"description":"Validation result created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageValidationResponse"}}}},"400":{"description":"Invalid or private URL"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/v1/page-validation/{id}":{"get":{"operationId":"getPageValidation","tags":["Page Validation"],"summary":"Fetch stored page validation by ID","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Validation record ID"}],"responses":{"200":{"description":"Stored validation record","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageValidationResponse"}}}},"404":{"description":"Validation record not found"}}}},"/api/v1/audit/run":{"post":{"operationId":"runVisibilityCompilerAudit","tags":["Visibility Compiler"],"summary":"Run a two-phase visibility compiler audit","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityCompilerAuditRunRequest"},"examples":{"default":{"summary":"Audit run request","value":{"url":"https://example.com/docs/ai-visibility","target_queries":["what is ai visibility","how to improve citation readiness"]}}}}}},"responses":{"201":{"description":"Visibility compiler audit completed and persisted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityCompilerAuditRunResponse"},"examples":{"default":{"summary":"Audit run response","value":{"success":true,"data":{"id":"b2a6714f-2a69-4e53-8fca-6a9561024b04","created_at":"2026-04-30T14:10:51.210Z","report":{"schema_version":"visibility_compiler_v1","run_id":"8f74ec2a-d3c2-4f9f-9fd2-3a9bb4f4934e","url":"https://example.com/docs/ai-visibility","target_queries":["what is ai visibility"],"status":"ready","sonar_compliance_score":78}}}}}}}},"400":{"description":"Invalid URL or missing required fields"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"}}}},"/api/v1/audit/results/{id}":{"get":{"operationId":"getVisibilityCompilerAuditResult","tags":["Visibility Compiler"],"summary":"Fetch visibility compiler audit results by ID","security":[{"apiKeyAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Visibility compiler audit ID"}],"responses":{"200":{"description":"Visibility compiler result payload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityCompilerAuditResultResponse"},"examples":{"default":{"summary":"Audit result response","value":{"success":true,"data":{"id":"b2a6714f-2a69-4e53-8fca-6a9561024b04","created_at":"2026-04-30T14:10:51.210Z","sonar_compliance_score":78,"json_ld_diagnostics":{"has_json_ld":true,"json_ld_count":2,"structural_gate_status":"ready"},"brag_findings":[{"brag_id":"ev_91f2a17d0d8c","diagnostic":"SemanticChunkMismatch","evidence_excerpt":"No extractable passage mapped for query: how to improve citation readiness","impact_score":0.72,"fix_path":{"action":"Add direct answer block under matching H2.","expected_gain":14,"technical_code":"## how to improve citation readiness"}}]}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"},"404":{"description":"Visibility compiler audit not found"}}}},"/api/v1/remediate/fixpack":{"post":{"operationId":"createVisibilityCompilerFixpack","tags":["Visibility Compiler"],"summary":"Generate executable fixpack payloads from BRAG findings","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityCompilerFixpackRequest"},"examples":{"default":{"summary":"Fixpack request","value":{"audit_id":"b2a6714f-2a69-4e53-8fca-6a9561024b04","issue_list":[{"brag_id":"ev_91f2a17d0d8c","diagnostic":"SemanticChunkMismatch","action":"Add direct answer block under matching H2."}]}}}}}},"responses":{"201":{"description":"Fixpack generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityCompilerFixpackResponse"},"examples":{"default":{"summary":"Fixpack response","value":{"success":true,"data":{"audit_id":"b2a6714f-2a69-4e53-8fca-6a9561024b04","fixpack_version":"fixpack_v1","executable_payloads":[{"brag_id":"ev_91f2a17d0d8c","json_ld_patch":{"@context":"https://schema.org","@type":"WebPage"},"html_markdown_refactor":{"selector":"main","operation":"append","content":"## Remediation for SemanticChunkMismatch"}}]}}}}}}},"400":{"description":"Invalid request body"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"},"404":{"description":"Visibility compiler audit not found"}}}},"/api/v1/monitor/track-velocity":{"post":{"operationId":"trackCitationVelocity","tags":["Visibility Compiler"],"summary":"Track citation velocity for a domain across a query set","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityCompilerVelocityTrackRequest"},"examples":{"default":{"summary":"Velocity tracking request","value":{"domain":"example.com","query_set":["what is ai visibility","best ai citation readiness tools"]}}}}}},"responses":{"200":{"description":"Citation velocity trend output","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VisibilityCompilerVelocityTrackResponse"},"examples":{"default":{"summary":"Velocity tracking response","value":{"success":true,"data":{"velocity_trend":{"domain":"example.com","total_queries":2,"cited_queries":1,"citation_rate":50,"trend_points":[{"query":"what is ai visibility","cited":true,"rank":2,"excerpt":"AiVIS Cite Ledger evidence and citation-readiness reference block..."}]}}}}}}}},"400":{"description":"Invalid request body"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"}}}},"/api/payment/stripe":{"post":{"operationId":"createStripeCheckoutSession","tags":["Payments"],"summary":"Create a Stripe checkout session for subscription purchase","security":[{"apiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tier"],"properties":{"tier":{"type":"string","enum":["observer","starter","alignment","signal","agency","scorefix"]},"brandDomain":{"type":"string","description":"Optional FQDN for branding context"}}}}}},"responses":{"200":{"description":"Stripe checkout session created"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/InsufficientScope"}},"x-payment-info":{"intent":"session","method":"stripe","amount":"dynamic","currency":"USD"}}},"/api/payment/scan-pack/checkout":{"post":{"operationId":"createScanPackCheckoutSession","tags":["Payments"],"summary":"Create a Stripe checkout session for scan-pack credits","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Stripe checkout session created for scan pack"},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-payment-info":{"intent":"charge","method":"stripe","amount":"dynamic","currency":"USD"}}},"/api/payment/portal":{"post":{"operationId":"createBillingPortalSession","tags":["Payments"],"summary":"Create a Stripe customer portal session","security":[{"apiKeyAuth":[]}],"responses":{"200":{"description":"Customer portal session created"},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-payment-info":{"intent":"session","method":"stripe","amount":0,"currency":"USD"}}},"/api/compliance/policy":{"get":{"operationId":"getPolicy","tags":["Compliance"],"summary":"Get consumer policy and disclaimer metadata","security":[],"responses":{"200":{"description":"Policy metadata"}}}},"/api/compliance/consent":{"get":{"operationId":"getConsent","tags":["Compliance"],"summary":"List consent records for account/workspace","description":"Requires session authentication (not API key).","security":[],"responses":{"200":{"description":"Consent records"},"401":{"description":"Session authentication required"}}},"post":{"operationId":"updateConsent","tags":["Compliance"],"summary":"Create or update consent status","description":"Requires session authentication (not API key).","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"consent_type":{"type":"string"},"granted":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Consent updated"},"401":{"description":"Session authentication required"}}}}},"components":{"securitySchemes":{"apiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"avis_*","description":"API key authentication. Keys are prefixed with avis_ and managed from your AiVIS Cite Ledger account settings."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"string"},"code":{"type":"string","enum":["INVALID_API_KEY","API_KEY_EXPIRED","FEATURE_LOCKED","INSUFFICIENT_SCOPE","RATE_LIMITED"]}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"has_more":{"type":"boolean"}}},"AuditSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"visibility_score":{"type":"number"},"created_at":{"type":"string","format":"date-time"}}},"AuditListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditSummary"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"AuditDetailResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"visibility_score":{"type":"number"},"result":{"type":"object","description":"Full audit result payload including recommendations, content analysis, technical signals, and AI platform scores"},"created_at":{"type":"string","format":"date-time"}}}}},"AnalyticsResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"scores":{"type":"array","items":{"type":"object","properties":{"score":{"type":"number"},"date":{"type":"string","format":"date-time"}}}}}}},"summary":{"type":"object","properties":{"total_audits":{"type":"integer"},"avg_score":{"type":"number"},"best_score":{"type":"number"},"worst_score":{"type":"number"}}},"platform_averages":{"type":"object","properties":{"chatgpt":{"type":"number"},"perplexity":{"type":"number"},"google_ai":{"type":"number"},"claude":{"type":"number"}}},"period_days":{"type":"integer"}}},"CompetitorListResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"competitor_url":{"type":"string"},"nickname":{"type":"string"},"latest_score":{"type":"number"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}},"EvidenceResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"audit_id":{"type":"string","format":"uuid"},"url":{"type":"string"},"scanned_at":{"type":"string","format":"date-time"},"evidence_fields":{"type":"object","description":"Evidence manifest keyed by signal category"},"content_highlights":{"type":"array","items":{"type":"object"}},"recommendation_evidence":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"priority":{"type":"string"},"category":{"type":"string"},"evidence_ids":{"type":"array","items":{"type":"string"}}}}}}}}},"UsageResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"monthStart":{"type":"string","format":"date"},"monthEnd":{"type":"string","format":"date"},"apiKeyRequestsThisMonth":{"type":"integer"},"workspaceRequestsThisMonth":{"type":"integer"}}}}},"PageValidationResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"result":{"type":"object","properties":{"status_code":{"type":"integer"},"final_url":{"type":"string"},"checks":{"type":"object","properties":{"hasTitle":{"type":"boolean"},"hasMetaDescription":{"type":"boolean"},"hasCanonical":{"type":"boolean"},"hasSingleH1":{"type":"boolean"},"hasJsonLd":{"type":"boolean"},"minWordCount300":{"type":"boolean"},"usesHttps":{"type":"boolean"}}},"metrics":{"type":"object","properties":{"title_length":{"type":"integer"},"meta_description_length":{"type":"integer"},"h1_count":{"type":"integer"},"json_ld_count":{"type":"integer"},"word_count":{"type":"integer"}}},"summary":{"type":"object","properties":{"passed":{"type":"integer"},"total":{"type":"integer"},"score_percent":{"type":"integer"}}}}},"created_at":{"type":"string","format":"date-time"}}}}},"VisibilityCompilerAuditRunRequest":{"type":"object","required":["url","target_queries"],"properties":{"url":{"type":"string","format":"uri"},"target_queries":{"type":"array","minItems":1,"items":{"type":"string"}}}},"VisibilityCompilerReport":{"type":"object","properties":{"schema_version":{"type":"string","enum":["visibility_compiler_v1"]},"run_id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"target_queries":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["ready","fail_structural"]},"sonar_compliance_score":{"type":"number"},"inference":{"type":"object","additionalProperties":true},"training":{"type":"object","additionalProperties":true},"findings":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityCompilerBragFinding"}}}},"VisibilityCompilerBragFinding":{"type":"object","properties":{"brag_id":{"type":"string"},"diagnostic":{"type":"string"},"evidence_excerpt":{"type":"string"},"impact_score":{"type":"number"},"fix_path":{"type":"object","properties":{"action":{"type":"string"},"expected_gain":{"type":"number"},"technical_code":{"type":"string"}}}}},"VisibilityCompilerAuditRunResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"report":{"$ref":"#/components/schemas/VisibilityCompilerReport"}}}}},"VisibilityCompilerJsonLdDiagnostics":{"type":"object","properties":{"has_json_ld":{"type":"boolean"},"json_ld_count":{"type":"integer"},"structural_gate_status":{"type":"string"}}},"VisibilityCompilerAuditResultResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"created_at":{"type":"string","format":"date-time"},"sonar_compliance_score":{"type":"number"},"json_ld_diagnostics":{"$ref":"#/components/schemas/VisibilityCompilerJsonLdDiagnostics"},"brag_findings":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityCompilerBragFinding"}},"report":{"$ref":"#/components/schemas/VisibilityCompilerReport"}}}}},"VisibilityCompilerFixpackRequest":{"type":"object","required":["audit_id"],"properties":{"audit_id":{"type":"string","format":"uuid"},"issue_list":{"type":"array","items":{"type":"object","properties":{"brag_id":{"type":"string"},"diagnostic":{"type":"string"},"evidence_excerpt":{"type":"string"},"action":{"type":"string"}}}}}},"VisibilityCompilerFixpackResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"audit_id":{"type":"string","format":"uuid"},"fixpack_version":{"type":"string","enum":["fixpack_v1"]},"executable_payloads":{"type":"array","items":{"type":"object","properties":{"brag_id":{"type":"string"},"json_ld_patch":{"type":"object","additionalProperties":true},"html_markdown_refactor":{"type":"object","properties":{"selector":{"type":"string"},"operation":{"type":"string"},"content":{"type":"string"}}}}}}}}}},"VisibilityCompilerVelocityTrackRequest":{"type":"object","required":["domain","query_set"],"properties":{"domain":{"type":"string"},"query_set":{"type":"array","minItems":1,"items":{"type":"string"}}}},"VisibilityCompilerVelocityTrendPoint":{"type":"object","properties":{"query":{"type":"string"},"cited":{"type":"boolean"},"rank":{"type":"integer","nullable":true},"excerpt":{"type":"string"}}},"VisibilityCompilerVelocityTrackResponse":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"velocity_trend":{"type":"object","properties":{"domain":{"type":"string"},"total_queries":{"type":"integer"},"cited_queries":{"type":"integer"},"citation_rate":{"type":"number"},"trend_points":{"type":"array","items":{"$ref":"#/components/schemas/VisibilityCompilerVelocityTrendPoint"}}}}}}}}},"responses":{"Unauthorized":{"description":"Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InsufficientScope":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Rate limit exceeded (120 requests / 60 seconds per key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}