{"openapi":"3.0.3","info":{"title":"VITNA API (Phase 1)","version":"1.1.0","description":"The compliance evidence layer for AI agents. Pre-flight compliance checks agents call before they act (consent, breach reportability, EU AI Act classification, cross-border), and audit-grade, signed records of what they did. Phase 1 surface covers regional data residency, DPIA/ROPA generation, Data Subject Rights, consent lifecycle, Sahamati AA integration, breach notification, and INR/Razorpay billing for DPDP-IN owners. Also includes one-command agent self-provisioning (/api/setup, mints a restricted trial key with no signup), a destructive-action safety pre-flight (/api/preflight/action-check), scoped engagement sessions with signed evidence bundles (/api/engagement/*), and account claim (/api/owners/claim).","contact":{"name":"COSTRINITY","email":"dpo@costrinity.xyz","url":"https://costrinity.xyz"},"license":{"name":"Proprietary","url":"https://vitna.costrinity.xyz/terms"}},"servers":[{"url":"https://vitna.costrinity.xyz","description":"Production"},{"url":"https://vigil-staging.vercel.app","description":"Staging (preview branch)"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-vigil-key","description":"Per-agent API key. Format: vigil_<32-char-hex>. Send on /api/ingest."},"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"vigil_<key>","description":"Same key as x-vigil-key, sent as `Authorization: Bearer <key>`."},"Session":{"type":"apiKey","in":"cookie","name":"vigil_session","description":"Operator dashboard session cookie. Set by /api/auth/verify-pin."},"CronSecret":{"type":"http","scheme":"bearer","description":"Bearer ${CRON_SECRET}. Only the Vercel cron infrastructure should hold this."}},"schemas":{"JurisdictionId":{"type":"string","enum":["DPDP-IN","GDPR-EU","CPRA-CA","LGPD-BR","PDPA-SG","US-FED"]},"RegionId":{"type":"string","enum":["us-east-1","ap-south-1","eu-west-1"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"detail":{"type":"string"}}},"ConsentArtifact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"principal_id":{"type":"string","format":"uuid"},"source":{"type":"string","enum":["sahamati-aa","dpdp-cm","gdpr-self","cpra-self","lgpd-self","pdpa-self","operator-attested"]},"purpose_codes":{"type":"array","items":{"type":"string"}},"permitted_categories":{"type":"array","items":{"type":"string"}},"consent_start":{"type":"string","format":"date-time"},"consent_expiry":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true},"signature_verified":{"type":"boolean"},"frequency_max":{"type":"integer","nullable":true},"frequency_window_hours":{"type":"integer","nullable":true}}},"ConsentCheckResult":{"type":"object","required":["allowed","reason","matching_consent_id","principal_id"],"properties":{"allowed":{"type":"boolean"},"reason":{"type":"string","nullable":true,"enum":[null,"no_principal","no_active_consent","purpose_mismatch","category_overflow"]},"matching_consent_id":{"type":"string","format":"uuid","nullable":true},"principal_id":{"type":"string","format":"uuid","nullable":true}}},"Phase1Health":{"type":"object","properties":{"ok":{"type":"boolean"},"phase":{"type":"string","enum":["1"]},"generated_at":{"type":"string","format":"date-time"},"required":{"type":"object","properties":{"primary_supabase_reachable":{"type":"boolean"},"cron_secret_configured":{"type":"boolean"},"resend_configured":{"type":"boolean"}}},"optional":{"type":"object","properties":{"dpia_snapshots_migration_applied":{"type":"boolean"},"razorpay_configured":{"type":"boolean"},"sahamati_strict_mode":{"type":"boolean"},"regions_provisioned":{"type":"array","items":{"$ref":"#/components/schemas/RegionId"}}}},"surface":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/health/regions":{"get":{"summary":"List provisioned Supabase regions","tags":["health"],"responses":{"200":{"description":"OK"}}}},"/api/health/phase1":{"get":{"summary":"Phase 1 readiness probe","tags":["health"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Phase1Health"}}}}}}},"/api/data-rights/summary":{"get":{"summary":"Catalogue of data-subject rights by jurisdiction","tags":["data-rights"],"parameters":[{"name":"jurisdiction","in":"query","schema":{"$ref":"#/components/schemas/JurisdictionId"}}],"responses":{"200":{"description":"Public catalogue"}}}},"/api/data-rights/access":{"get":{"summary":"Right of access, full principal record","tags":["data-rights"],"security":[{"Session":[]}],"parameters":[{"name":"principal_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","portable"]}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"404":{"description":"Principal not found"}}}},"/api/data-rights/portability":{"get":{"summary":"Right to data portability (GDPR Art 20), JSON-LD export","tags":["data-rights"],"security":[{"Session":[]}],"parameters":[{"name":"principal_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"type":"string","enum":["jsonld","json"]}}],"responses":{"200":{"description":"JSON-LD or JSON"}}}},"/api/data-rights/correction":{"post":{"summary":"Right of correction, files an incident","tags":["data-rights"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/data-rights/erasure":{"post":{"summary":"Right to erasure, cascading delete + event anonymization","tags":["data-rights"],"security":[{"Session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["principal_id","confirm"],"properties":{"principal_id":{"type":"string","format":"uuid"},"scope":{"type":"string","enum":["all","events","consents"]},"confirm":{"type":"boolean","enum":[true]}}}}}},"responses":{"200":{"description":"OK"}}}},"/api/data-rights/grievance":{"post":{"summary":"Public grievance filing (no auth, IP rate-limited)","tags":["data-rights","public"],"parameters":[{"name":"owner_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"429":{"description":"Rate limited"}}}},"/api/data-rights/object":{"get":{"summary":"List active objections for a principal (GDPR Art 21)","tags":["data-rights"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Object to specific processing (GDPR Art 21)","tags":["data-rights"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/compliance/dpia":{"get":{"summary":"Live DPIA generation","tags":["compliance"],"security":[{"Session":[]}],"parameters":[{"name":"owner_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}}],"responses":{"200":{"description":"DPIA document"}}}},"/api/compliance/dpia-snapshots":{"get":{"summary":"Historical DPIA snapshots (from /api/cron/dpia-refresh)","tags":["compliance"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/compliance/ropa":{"get":{"summary":"Record of Processing Activities (GDPR Art 30 / DPDP §6(2))","tags":["compliance"],"security":[{"Session":[]}],"responses":{"200":{"description":"ROPA document"}}}},"/api/compliance/sub-processors":{"get":{"summary":"Public sub-processor register (GDPR Art 28(2))","tags":["compliance","public"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}}],"responses":{"200":{"description":"Register"}}}},"/api/compliance/pii-test":{"post":{"summary":"Dry-run PII/threat detection against a sample event (no persistence)","tags":["compliance","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Detection result"}}}},"/api/compliance/privacy-notice":{"get":{"summary":"Generate jurisdiction-templated privacy notice the Operator publishes","tags":["compliance"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}}],"responses":{"200":{"description":"Privacy notice"}}}},"/api/compliance/dpa-template":{"get":{"summary":"Generate Article 28-shape Data Processing Agreement template","tags":["compliance"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}}],"responses":{"200":{"description":"DPA template"}}}},"/api/compliance/health":{"get":{"summary":"Operator compliance posture roll-up (single JSON for the dashboard widget)","tags":["compliance"],"security":[{"Session":[]}],"responses":{"200":{"description":"Posture document"}}}},"/api/compliance/breach-classify":{"post":{"summary":"Decision-support: is this incident reportable per jurisdiction?","tags":["compliance","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Classification result"}}}},"/api/audit-log":{"get":{"summary":"Owner-scoped chronological audit trail (merged across 5 tables)","tags":["audit"],"security":[{"Session":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"kind","in":"query","schema":{"type":"string","description":"CSV: consent_access,consent_grant,consent_revoke,incident,breach_notification,dpia_snapshot"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":1000}}],"responses":{"200":{"description":"Audit events"}}}},"/api/compliance/scc-annex-ii":{"get":{"summary":"Standard Contractual Clauses Annex II (technical + organisational measures)","tags":["compliance"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}}],"responses":{"200":{"description":"Annex II document"}}}},"/api/compliance/dpia-threshold-check":{"post":{"summary":"Decision-support: is a DPIA mandatory for this processing? (9-criterion WP29 check)","tags":["compliance","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Threshold decision"}}}},"/api/owners/notification-prefs/test":{"post":{"summary":"Fire a synthetic notification to verify operator's configured channel works","tags":["owner"],"security":[{"Session":[]}],"responses":{"200":{"description":"Dispatched"}}}},"/api/owners/grievance-officer":{"get":{"summary":"Read operator's Grievance Officer config (DPDP §9)","tags":["owner","india"],"security":[{"Session":[]}],"responses":{"200":{"description":"Officer config or null"}}},"post":{"summary":"Set operator's Grievance Officer (DPDP §9 / LGPD Art 41)","tags":["owner","india"],"security":[{"Session":[]}],"responses":{"200":{"description":"Recorded"}}}},"/api/pricing/local":{"get":{"summary":"Plan prices in local currency + SOL equivalent","tags":["public","pricing"],"parameters":[{"name":"country","in":"query","schema":{"type":"string","description":"ISO-3166 alpha-2"}},{"name":"owner_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Localized prices"}}}},"/api/payment-methods/india":{"get":{"summary":"Public guide: how Indian customers pay for VITNA (Solana Pay / PayPal / Razorpay)","tags":["public","india"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Payment guide"}}}},"/api/compliance/india-status":{"get":{"summary":"Public DPDP / India compliance posture (live vs planned per capability)","tags":["public","compliance","india"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Posture document"}}}},"/api/compliance/cross-border-notice":{"get":{"summary":"DPDP §16 cross-border transfer notice the operator distributes to data principals","tags":["compliance","india"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}}],"responses":{"200":{"description":"Notice document"}}}},"/api/compliance/dpdp-checklist":{"get":{"summary":"Per-operator DPDP requirement checklist (configured/pending/N/A per §)","tags":["compliance","india"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Checklist"}}}},"/api/compliance/na-status":{"get":{"summary":"Public NA compliance posture (Canada PIPEDA + US sectoral + state matrix)","tags":["compliance","public","north-america"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Posture"}}}},"/api/compliance/us-state-matrix":{"get":{"summary":"US state privacy law matrix (16+ states with criteria, rights, DPIA reqs, UOOM support)","tags":["compliance","public","north-america"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Matrix"}}}},"/api/compliance/state-breach-deadlines":{"get":{"summary":"US state breach notification deadlines + AG recipient registry","tags":["compliance","public","north-america"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}},{"name":"state","in":"query","schema":{"type":"string","description":"ISO 2-letter state code"}}],"responses":{"200":{"description":"Deadlines"}}}},"/api/compliance/nist-pf-posture":{"get":{"summary":"NIST Privacy Framework v1.0 posture for the operator (5 Functions, signal-driven scoring)","tags":["compliance","north-america"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Posture"}}}},"/api/compliance/sectoral-check":{"post":{"summary":"US sectoral law applicability (HIPAA / GLBA / COPPA / FERPA / FCRA / SOX)","tags":["compliance","tools","north-america"],"security":[{"Session":[]}],"responses":{"200":{"description":"Sectoral matches"}}}},"/api/compliance/indigenous-data":{"get":{"summary":"COSTRINITY's public Indigenous data sovereignty position (OCAP™, CARE, UNDRIP)","tags":["compliance","public","north-america"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Position document"}}}},"/api/india/aadhaar-mask":{"post":{"summary":"Mask + Verhoeff-validate an Aadhaar (server-side; no persistence)","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Masked + reference token"}}}},"/api/india/verhoeff-verify":{"post":{"summary":"Verhoeff D5 checksum verification for 12-digit numbers (no persistence)","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validity"}}}},"/api/india/pan-classify":{"post":{"summary":"PAN entity-type classification from 4th character","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Entity classification"}}}},"/api/india/upi-validate":{"post":{"summary":"UPI handle format + PSP recognition","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"UPI validation"}}}},"/api/india/gstn-validate":{"post":{"summary":"GSTIN format + check-digit + state-code lookup","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"GSTIN validation"}}}},"/api/india/regulators":{"get":{"summary":"Public directory of India sectoral regulators (RBI/SEBI/IRDAI/TRAI/etc.)","tags":["india","public"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}},{"name":"sector","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Regulator directory"}}}},"/api/compliance/india-sectoral-check":{"post":{"summary":"Indian sectoral regulator applicability (RBI/SEBI/IRDAI/TRAI/PFRDA)","tags":["compliance","india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Sectoral matches"}}}},"/api/compliance/india-cross-border-countries":{"get":{"summary":"DPDP §16 cross-border destination country registry","tags":["compliance","india","public"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}},{"name":"country","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Country registry"}}}},"/api/india/mobile-validate":{"post":{"summary":"Indian mobile +91 format + operator/circle hint (MNP-caveated)","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/india/ifsc-validate":{"post":{"summary":"IFSC format + bank code recognition (~50 banks)","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/india/pincode-validate":{"post":{"summary":"PIN code format + region/state hint (India Post numbering plan)","tags":["india","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/canada/sin-validate":{"post":{"summary":"Canadian SIN format + Luhn checksum + series-region hint (no persistence)","tags":["canada","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/compliance/ca-province-matrix":{"get":{"summary":"Canadian provincial privacy law matrix (PIPEDA + Loi 25 + Alberta/BC PIPA + Manitoba/Ontario PHIA)","tags":["compliance","canada","public","north-america"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}},{"name":"province","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Matrix"}}}},"/api/compliance/quebec-law25":{"get":{"summary":"Per-operator Quebec Law 25 (Loi 25) readiness scorecard","tags":["compliance","canada"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/soc2-readiness":{"get":{"summary":"SOC 2 Trust Service Criteria readiness scorecard (pre-audit)","tags":["compliance","enterprise","north-america"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/japan/mynumber-validate":{"post":{"summary":"Japan My Number 12-digit format + mod-11 checksum (no persistence)","tags":["japan","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/nigeria/nin-validate":{"post":{"summary":"Nigeria NIN format validator (no persistence)","tags":["nigeria","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/nigeria/bvn-validate":{"post":{"summary":"Nigeria BVN format validator (no persistence)","tags":["nigeria","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/eu/iban-validate":{"post":{"summary":"IBAN mod-97 (ISO 7064) validator + country length lookup","tags":["eu","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/eu/vat-validate":{"post":{"summary":"EU VAT format validator per member state pattern","tags":["eu","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/compliance/appi-readiness":{"get":{"summary":"Japan APPI readiness scorecard (Art 17/18/21/23/26/28/30/35/40)","tags":["compliance","japan"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/ndpa-readiness":{"get":{"summary":"Nigeria NDPA 2023 readiness scorecard (§24/25/26/27/28/32/33/40/41)","tags":["compliance","nigeria"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/ai-act-classify":{"post":{"summary":"EU AI Act risk classifier (prohibited / high-risk / limited / minimal + GPAI obligations)","tags":["compliance","eu","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Classification"}}}},"/api/compliance/dsa-status":{"post":{"summary":"EU Digital Services Act applicability (intermediary / hosting / online platform / VLOP)","tags":["compliance","eu","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"DSA tier"}}}},"/api/compliance/japan-cross-border":{"get":{"summary":"Japan APPI Art 28 cross-border country registry","tags":["compliance","japan","public"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}},{"name":"country","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Registry"}}}},"/api/compliance/global-status":{"get":{"summary":"Master endpoint listing every privacy/security/sectoral regime VITNA covers","tags":["compliance","public"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Global status"}}}},"/api/compliance/hipaa-readiness":{"get":{"summary":"HIPAA Business Associate readiness scorecard (45 CFR §§164.308-316)","tags":["compliance","enterprise"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/iso27001-readiness":{"get":{"summary":"ISO/IEC 27001:2022 Annex A readiness (22 controls evaluated)","tags":["compliance","enterprise"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/pci-dss-readiness":{"get":{"summary":"PCI DSS v4.0 readiness (12 requirements)","tags":["compliance","enterprise"],"security":[{"Session":[]}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/uk-gdpr-readiness":{"get":{"summary":"UK GDPR + DPA 2018 readiness","tags":["compliance","uk"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/pipa-kr-readiness":{"get":{"summary":"South Korea PIPA readiness (24h breach window)","tags":["compliance","korea"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/app-au-readiness":{"get":{"summary":"Australia Privacy Act + 13 APPs readiness","tags":["compliance","australia"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/compliance/pipl-cn-readiness":{"get":{"summary":"China PIPL readiness scorecard","tags":["compliance","china"],"security":[{"Session":[]}],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","md"]}}],"responses":{"200":{"description":"Readiness"}}}},"/api/uk/nin-validate":{"post":{"summary":"UK National Insurance Number validator (no persistence)","tags":["uk","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/korea/rrn-validate":{"post":{"summary":"Korea RRN 13-digit + weighted mod-11 + century/sex decode (no persistence)","tags":["korea","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/australia/tfn-validate":{"post":{"summary":"Australia TFN + weighted mod-11 checksum (no persistence)","tags":["australia","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/australia/abn-validate":{"post":{"summary":"Australia ABN + first-1 + mod-89 checksum (no persistence)","tags":["australia","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/china/id-card-validate":{"post":{"summary":"China ID Card 18-char + ISO 7064 mod-11-2 + region/birth/sex decode (no persistence)","tags":["china","tools"],"security":[{"Session":[]}],"responses":{"200":{"description":"Validation result"}}}},"/api/changelog":{"get":{"summary":"Public VITNA changelog (hand-curated operator-facing milestones)","tags":["public"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}},{"name":"since","in":"query","schema":{"type":"string","description":"Filter to phase ≥ N"}}],"responses":{"200":{"description":"Changelog"}}}},"/api/.well-known/openapi":{"get":{"summary":"This document, OpenAPI 3.0 spec covering the Phase 1 surface","tags":["public","meta"],"parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","yaml"]}}],"responses":{"200":{"description":"OpenAPI document"}}}},"/api/consent/request":{"post":{"summary":"Record a new consent artifact","tags":["consent"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/consent/revoke":{"post":{"summary":"Revoke a specific consent artifact","tags":["consent"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/consent/active":{"get":{"summary":"List active (unrevoked, unexpired) consents","tags":["consent"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/consent/check":{"get":{"summary":"Pre-flight enforcement, is processing allowed?","tags":["consent"],"security":[{"Session":[]}],"parameters":[{"name":"principal_id","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"principal_ref","in":"query","schema":{"type":"string"}},{"name":"purpose","in":"query","required":true,"schema":{"type":"string"}},{"name":"category","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentCheckResult"}}}}}},"post":{"summary":"Pre-flight enforcement (POST variant)","tags":["consent"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/consent/renew":{"post":{"summary":"Extend an active consent's expiry","tags":["consent"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/consent/bulk-revoke":{"post":{"summary":"Revoke ALL active consents for a principal","tags":["consent"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/consent/receipt":{"get":{"summary":"Downloadable Kantara-shaped consent receipt","tags":["consent"],"security":[{"Session":[]}],"parameters":[{"name":"consent_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","schema":{"type":"string","enum":["md","json"]}}],"responses":{"200":{"description":"OK"}}}},"/api/sahamati/consent-handle":{"post":{"summary":"Sahamati Account Aggregator consent webhook","tags":["consent","india"],"parameters":[{"name":"x-sahamati-signature","in":"header","schema":{"type":"string"},"description":"JWS header.payload.signature (RS256). Verified against SAHAMATI_PUBKEY_PEM when set."}],"responses":{"200":{"description":"OK"},"401":{"description":"Signature invalid"}}}},"/api/owners":{"post":{"summary":"Sign up / create owner (region-aware)","tags":["owner"],"responses":{"201":{"description":"Created"}}}},"/api/owners/delete-account":{"post":{"summary":"Full operator account deletion (DPDP §12 / GDPR Art 17)","tags":["owner"],"security":[{"Session":[]}],"responses":{"200":{"description":"Deleted"}}}},"/api/owners/notification-prefs":{"get":{"summary":"Read operator notification preferences","tags":["owner"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Update operator notification preferences","tags":["owner"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/incidents/breach-notify":{"get":{"summary":"Read notification state for an incident","tags":["breach"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}},"post":{"summary":"Queue a breach notification (per-jurisdiction window)","tags":["breach"],"security":[{"Session":[]}],"responses":{"200":{"description":"OK"}}}},"/api/upgrade/razorpay/order":{"post":{"summary":"Create Razorpay INR order (DPDP-IN owners)","tags":["billing","india"],"security":[{"Session":[]}],"responses":{"200":{"description":"Order created"},"503":{"description":"Skip-mode — Razorpay env triple not configured"}}}},"/api/webhooks/razorpay":{"post":{"summary":"Razorpay payment webhook","tags":["billing","india"],"parameters":[{"name":"x-razorpay-signature","in":"header","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Signature invalid"}}}},"/api/webhooks/compliance/register":{"post":{"summary":"Register a compliance webhook endpoint","description":"Operator registers a URL to receive a specific compliance event kind (breach_notification, grievance_filed, consent_revoked, data_subject_request, cross_border_transfer, dpia_threshold_triggered). Deliveries are signed with HMAC-SHA256 and audit-logged.","tags":["webhooks","compliance"],"security":[{"ApiKey":[]}],"responses":{"200":{"description":"Endpoint registered"},"400":{"description":"Invalid event_kind or url"},"401":{"description":"Auth required"}}}},"/api/webhooks/compliance/list":{"get":{"summary":"List registered compliance webhook endpoints","tags":["webhooks","compliance"],"security":[{"ApiKey":[]}],"parameters":[{"name":"event_kind","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Auth required"}}}},"/api/webhooks/compliance/test":{"post":{"summary":"Fire a test compliance webhook","description":"Sends a synthetic breach_notification payload (data.test=true) to one or all active endpoints. Helps operators verify their receiver before the first real event.","tags":["webhooks","compliance"],"security":[{"ApiKey":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Auth required"}}}},"/api/webhooks/compliance/deliveries":{"get":{"summary":"Read compliance webhook delivery audit log","description":"Returns every delivery attempt (delivered + failed + SSRF-refused) with payload_sha256 for tamper-evidence. The regulator-facing proof log.","tags":["webhooks","compliance","audit"],"security":[{"ApiKey":[]}],"parameters":[{"name":"event_kind","in":"query","schema":{"type":"string"}},{"name":"delivered","in":"query","schema":{"type":"boolean"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":500}}],"responses":{"200":{"description":"OK"},"401":{"description":"Auth required"}}}},"/api/cron/check-alerts":{"get":{"summary":"Scheduled alert + heartbeat evaluation (5-min Vercel cron)","tags":["cron"],"security":[{"CronSecret":[]}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"}}}},"/api/cron/dpia-refresh":{"get":{"summary":"Scheduled DPIA snapshot refresh (weekly Sunday cron)","tags":["cron"],"security":[{"CronSecret":[]}],"responses":{"200":{"description":"OK"}}}},"/api/ingest":{"post":{"summary":"Ingest agent event (single or batch)","tags":["ingest"],"security":[{"ApiKey":[]},{"Bearer":[]}],"responses":{"200":{"description":"OK (or 202 if storage_mode=local)"},"401":{"description":"Invalid API key"},"413":{"description":"Body or batch too large"},"429":{"description":"Rate limited"}}}},"/api/setup":{"post":{"summary":"One-command agent self-provisioning: create/resolve an owner and mint an API key (a RESTRICTED trial key for a fresh email, no signup)","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_name"],"properties":{"agent_name":{"type":"string"},"owner_email":{"type":"string","description":"Required unless owner_id is given. A fresh email mints a RESTRICTED trial key."},"owner_id":{"type":"string","format":"uuid","description":"Attach to an existing owner instead (mints a full key)."},"description":{"type":"string"},"capabilities":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Existing agent for this owner+name; api_key is null (rotate to get a new one)."},"201":{"description":"Created. Returns agent_id, api_key (shown once), owner_id; for a fresh email also restricted:true + claim_url + trial{daily_checks,lifetime_checks,expires_at}."},"400":{"description":"agent_name and (owner_email or owner_id) required"},"403":{"description":"Email not verified (existing owner), or free-plan agent limit reached"},"429":{"description":"IP rate limited (20 / 10 min)"}}}},"/api/preflight/action-check":{"post":{"summary":"Safety pre-flight: check a dangerous action (shell / file / DB / network) BEFORE you run it -> allowed | blocked | flagged. VITNA evaluates + records; the caller enforces","tags":["agent","safety"],"security":[{"ApiKey":[]},{"Bearer":[]},{"Session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","description":"Proposed command/action text, e.g. \"rm -rf /\"."},"payload":{"type":"object"},"action_type":{"type":"string"}}}}}},"responses":{"200":{"description":"Full key: {decision, threat_category, severity, reason, threats[], redacted_action, ...}. Restricted trial key: label-only {check, effect, decision, flagged, trial:true}."},"400":{"description":"Provide action and/or payload"},"401":{"description":"Forbidden (missing/invalid key)"},"403":{"description":"Restricted key: key_expired"},"429":{"description":"Restricted-key cap: daily_cap_reached / lifetime_cap_reached / global_capacity_reached / too_many_concurrent"},"503":{"description":"audit_record_write_failed (fail-closed), or service_paused / metering_unavailable"}}}},"/api/engagement/open":{"post":{"summary":"Open a scoped engagement session; VITNA evaluates every later action against its ScopePolicy","tags":["engagement"],"security":[{"ApiKey":[]},{"Bearer":[]},{"Session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["scope_policy"],"properties":{"scope_policy":{"type":"object","properties":{"allowed_domains":{"type":"array","items":{"type":"string"}},"allowed_actions":{"type":"array","items":{"type":"string"},"description":"Non-empty; forbid everything else."},"max_writes":{"type":"integer","nullable":true},"expires_at":{"type":"string","nullable":true}}},"metadata":{"type":"object"},"webhook_url":{"type":"string","description":"Optional https alert URL (SSRF-guarded)."}}}}}},"responses":{"200":{"description":"{session_id, status:\"open\", scope_policy, webhook_configured, opened_at}"},"400":{"description":"allowed_actions must be non-empty, or bad webhook_url"},"401":{"description":"Forbidden"},"402":{"description":"plan_limit_exceeded (active engagements: free 3 / pro 100 / team 500 / enterprise unlimited)"}}}},"/api/engagement/action":{"post":{"summary":"Per-action decision loop: evaluate one action against the session policy + threat detector -> allow | deny | hold with a signed VigilDecision","tags":["engagement"],"security":[{"ApiKey":[]},{"Bearer":[]},{"Session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id","type"],"properties":{"session_id":{"type":"string","format":"uuid"},"type":{"type":"string","description":"Whitespace-free action identifier, e.g. dns.write."},"target":{"type":"string","nullable":true},"payload":{"type":"object","nullable":true},"context":{"type":"object","nullable":true},"_meta":{"type":"object","description":"Optional W3C trace context (traceparent / tracestate)."}}}}}},"responses":{"200":{"description":"{decision:\"allow\"|\"deny\"|\"hold\", reason, threat_flags[], vigil_decision{...signature...}, alert, enforced_by:\"caller\"}. Restricted key: vigil_decision unsigned + trial:true."},"400":{"description":"session_id and type required; type must be whitespace-free"},"401":{"description":"Forbidden"},"404":{"description":"session_not_found"},"429":{"description":"Restricted-key caps"},"503":{"description":"audit_record_write_failed (fail-closed)"}}}},"/api/engagement/close":{"post":{"summary":"Close a session and emit a signed, offline-verifiable Ed25519 evidence bundle (claimed accounts only)","tags":["engagement"],"security":[{"ApiKey":[]},{"Bearer":[]},{"Session":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id"],"properties":{"session_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"{evidence_package, package_signature (Ed25519), verification{...}}"},"401":{"description":"Forbidden"},"403":{"description":"restricted_key_forbidden (signed evidence is a claimed-account capability)"},"404":{"description":"session_not_found"}}}},"/api/engagement/list":{"get":{"summary":"List the owner's engagements with state, scope, decision counts, and plan metering","tags":["engagement"],"security":[{"ApiKey":[]},{"Bearer":[]},{"Session":[]}],"parameters":[{"name":"owner_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"{count, metering, engagements[]}"},"401":{"description":"Forbidden"}}}},"/api/engagement/get":{"get":{"summary":"One engagement's full status + itemized decisions (owner-scoped)","tags":["engagement"],"security":[{"ApiKey":[]},{"Bearer":[]},{"Session":[]}],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"owner_id","in":"query","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"EngagementDetail"},"400":{"description":"session_id required"},"401":{"description":"Forbidden"},"404":{"description":"session_not_found"}}}},"/api/owners/claim":{"post":{"summary":"Claim step 1: bind a real email to an unclaimed trial owner and email a 6-digit code","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["owner_id","email"],"properties":{"owner_id":{"type":"string","format":"uuid"},"email":{"type":"string"}}}}}},"responses":{"200":{"description":"{sent:true, owner_id}"},"400":{"description":"valid owner_id / email required"},"404":{"description":"not_claimable"},"409":{"description":"not_claimable (not a trial account), or email_in_use"},"429":{"description":"IP rate limited (20 / 10 min)"}}}},"/api/owners/claim/confirm":{"post":{"summary":"Claim step 2: verify the code, bind + verify the email, and lift the restriction on all the owner's keys","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["owner_id","pin"],"properties":{"owner_id":{"type":"string","format":"uuid"},"pin":{"type":"string","pattern":"^\\d{6}$"}}}}}},"responses":{"200":{"description":"{claimed:true, owner_id, keys_unlocked}"},"400":{"description":"valid owner_id / pin required; no_claim_in_progress; code_expired"},"401":{"description":"invalid_code"},"404":{"description":"not_claimable"},"409":{"description":"email_in_use"},"429":{"description":"IP rate limited (30 / 10 min)"}}}}}}