Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: VITNA API (Phase 1) Compliance API
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 region routing labels (one database region is in use today), DPIA/ROPA generation, Data Subject Rights (scoped: answerable only for events linked to a subject via principal_ref at ingest, from the point linkage begins; earlier events are permanently unattributable and cannot be linked retroactively), consent lifecycle, Sahamati AA integration, breach notification, and INR/Razorpay billing for DPDP-IN owners (switched off pending merchant onboarding). 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 by a person, from the claim link (/claim).'
contact:
name: COSTRINITY
email: dpo@costrinity.xyz
url: https://www.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)
tags:
- name: Compliance
paths:
/api/compliance/dpia:
get:
summary: Live DPIA generation
description: 'Signed-in owner only (since 2026-11-01). With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) it is refused 403 session_required before anything is read, because these records are not tied to a session. The DPIA counts every agent''s events and tags.'
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
'401':
description: 'Unauthorized: no signed-in session, or owner_id names another account'
'403':
description: 'session_required: the request carried an API key'
operationId: getApiComplianceDpia
x-operation-id-source: derived
/api/compliance/dpia-snapshots:
get:
summary: Historical DPIA snapshots (from /api/cron/dpia-refresh)
description: 'Signed-in owner only (since 2026-11-01). With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) it is refused 403 session_required before anything is read, because these records are not tied to a session.'
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: OK
'401':
description: 'Unauthorized: no signed-in session, or owner_id names another account'
'403':
description: 'session_required: the request carried an API key'
operationId: getApiComplianceDpiaSnapshots
x-operation-id-source: derived
/api/compliance/ropa:
get:
summary: Record of Processing Activities (GDPR Art 30 / DPDP §6(2))
description: 'Signed-in owner only (since 2026-11-01). With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) it is refused 403 session_required before anything is read, because these records are not tied to a session. The record lists every agent and counts every agent''s events and the account''s consents.'
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: ROPA document
'401':
description: 'Unauthorized: no signed-in session, or owner_id names another account'
'403':
description: 'session_required: the request carried an API key'
operationId: getApiComplianceRopa
x-operation-id-source: derived
/api/compliance/sub-processors:
get:
summary: Public sub-processor register for the VITNA product and website (GDPR Art 28(2))
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- md
- json
responses:
'200':
description: 'Register. The JSON view is schema v2: provider_terms_url and dpa_url, either of which can be null, replace public_dpa_url.'
operationId: getApiComplianceSubProcessors
x-operation-id-source: derived
/api/compliance/pii-test:
post:
summary: Dry-run PII/threat detection against a sample event (no persistence)
description: 'sample_event.payload is read as /api/ingest reads it. A payload that is not a JSON object (text, a number, true or false, or an array) is kept whole as {"value": } and checked like any other field. Each threat found in the payload carries path, the exact place of the matched value (object keys as strings, array indices as numbers), beside field, which joins the key names for display. Redaction replaces the value at path, so a field whose key contains a dot or a bracket is replaced like any other. A match in a key carries in_key true, and its path and field are those of the object the key is in. A key in which the detectors find a secret or a regulated identifier is named "[redacted: ]" in the path and field of every threat below it, so no threat shows it. Before 2026-10-06 keys were not read. Each piece of text, list or object in the payload that lies more than 32 levels deep, after the first 1,000 items of a list, or after the first 10,000 pieces of text in the payload is not read by the detectors and is replaced as a whole with "[redacted: beyond scan limit]"; a number, true or false, or null there is kept, unless its key is past the text limit. At most 1,000 such parts in one request, across all its payloads, are replaced where they are; a payload whose parts would go past that is replaced whole instead, with {"value": "[redacted: beyond scan limit]"}. The keys of the objects in the payload are read too, each as a piece of text before its value, and count toward those 10,000. Where a key holds a leaked secret or a regulated identifier, the object it is in is replaced as a whole with "[redacted: ]", or, for a key at the top level of the payload, the whole payload with {"value": "[redacted: ]"}. A key after the first 10,000 pieces of text is not read, so it and the keys after it in its object, with their values, are replaced together by one entry, "[redacted: beyond scan limit]", whose value is how many entries it replaces, and count as one such part; when the object already has a key of that name before them, that key''s value is replaced by the count. Before 2026-10-06 the detectors read 8 levels deep and the first 100 items of a list, read no keys, and left what lay beyond as sent. A payload with such parts has one threat of category scan_limit listed for it, however many parts were replaced: severity info, label "beyond scan limit", the path of the first such part (for keys past the text limit, the path of their object, with in_key true) and no match_preview. It counts once in the summary and raises no severity.'
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: 'Detection result: {applied_jurisdiction, threats[{category, severity, label, field, match_preview, in_key?}], threats_omitted, compliance_tags, max_severity, summary, redacted_payload, redacted_message, would_escalate}. threats lists at most 1,000; threats_omitted counts the rest. field is where the match was ("message" or "payload.a.b[0]"), cut at 200 characters with "…" after them when it is longer. Before 2026-10-06 every threat was listed with its whole field and its path, so one long key over many matches made the answer about 200 times the sample. match_preview does not show the text of a secret or regulated identifier the detectors find. For a threat of category secret_leak or pii it is the first 2 and last 2 characters of the match with "****" between them when the match has 16 or more characters (an AWS access key id reads like "AK****LE"), and "[redacted: <label>]" when it has fewer. For the attack categories (sql_destructive, shell_dangerous, prompt_injection, exfiltration, suspicious_network) it is the matched text, which a responder needs, with each secret or regulated identifier the detectors find in it replaced with "[redacted: <label>]", cut to 80 characters. Detection is heuristic: text the patterns do not recognise is shown as matched. Before 2026-10-06 match_preview was the matched text, cut to 80 characters, for every category, so this dry run returned the secrets it was sent.'
operationId: postApiCompliancePiiTest
x-operation-id-source: derived
/api/compliance/privacy-notice:
get:
summary: Generate jurisdiction-templated privacy notice the Operator publishes
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the document prints "[operator name - visible when signed in]" and "[account contact email - visible when signed in]" in place of the operator''s name and contact address. The signed-in owner gets the real values.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- md
- json
responses:
'200':
description: Privacy notice
operationId: getApiCompliancePrivacyNotice
x-operation-id-source: derived
/api/compliance/dpa-template:
get:
summary: Generate Article 28-shape Data Processing Agreement template
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the document prints "[operator name - visible when signed in]" and "[account contact email - visible when signed in]" in place of the operator''s name and contact address. The signed-in owner gets the real values.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- md
- json
responses:
'200':
description: DPA template
operationId: getApiComplianceDpaTemplate
x-operation-id-source: derived
/api/compliance/health:
get:
summary: Operator compliance posture roll-up (single JSON for the dashboard widget)
description: 'Signed-in owner only (since 2026-11-01). With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) it is refused 403 session_required before anything is read, because these records are not tied to a session.'
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: Posture document
'401':
description: 'Unauthorized: no signed-in session, or owner_id names another account'
'403':
description: 'session_required: the request carried an API key'
operationId: getApiComplianceHealth
x-operation-id-source: derived
/api/compliance/breach-classify:
post:
summary: 'Decision-support: is this incident reportable per jurisdiction?'
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: Classification result
operationId: postApiComplianceBreachClassify
x-operation-id-source: derived
/api/compliance/scc-annex-ii:
get:
summary: Standard Contractual Clauses Annex II (technical + organisational measures)
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the document prints "[operator name - visible when signed in]" and "[account contact email - visible when signed in]" in place of the operator''s name and contact address. The signed-in owner gets the real values.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- md
- json
responses:
'200':
description: Annex II document
operationId: getApiComplianceSccAnnexIi
x-operation-id-source: derived
/api/compliance/dpia-threshold-check:
post:
summary: 'Decision-support: is a DPIA mandatory for this processing?'
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: Threshold decision
operationId: postApiComplianceDpiaThresholdCheck
x-operation-id-source: derived
/api/compliance/cross-border-notice:
get:
summary: DPDP §16 cross-border transfer notice the operator distributes to data…
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the document prints "[operator name - visible when signed in]" and "[account contact email - visible when signed in]" in place of the operator''s name and contact address. The signed-in owner gets the real values. The JSON form''s controller field is the name placeholder.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- md
- json
responses:
'200':
description: Notice document
operationId: getApiComplianceCrossBorderNotice
x-operation-id-source: derived
/api/compliance/dpdp-checklist:
get:
summary: Per-operator DPDP requirement checklist (configured/pending/N/A per §)
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the grievance officer row says configured or pending, and where it names the officer it prints "[officer name - visible when signed in]" and "[officer email - visible when signed in]" instead. The signed-in owner sees the officer''s name and address.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Checklist
operationId: getApiComplianceDpdpChecklist
x-operation-id-source: derived
/api/compliance/na-status:
get:
summary: Public NA compliance posture (Canada PIPEDA + US sectoral + state matrix)
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Posture
operationId: getApiComplianceNaStatus
x-operation-id-source: derived
/api/compliance/us-state-matrix:
get:
summary: US state privacy law matrix (16 states with criteria, rights, DPIA reqs, UOOM…
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Matrix
operationId: getApiComplianceUsStateMatrix
x-operation-id-source: derived
/api/compliance/state-breach-deadlines:
get:
summary: US state breach notification deadlines + AG recipient registry
tags:
- Compliance
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
operationId: getApiComplianceStateBreachDeadlines
x-operation-id-source: derived
/api/compliance/nist-pf-posture:
get:
summary: NIST Privacy Framework v1.0 posture for the operator (5 Functions…
tags:
- Compliance
security:
- Session: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Posture
operationId: getApiComplianceNistPfPosture
x-operation-id-source: derived
/api/compliance/sectoral-check:
post:
summary: US sectoral law applicability (HIPAA / GLBA / COPPA / FERPA / FCRA / SOX)
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: Sectoral matches
operationId: postApiComplianceSectoralCheck
x-operation-id-source: derived
/api/compliance/indigenous-data:
get:
summary: COSTRINITY's public Indigenous data sovereignty position (CARE, UNDRIP)
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Position document
operationId: getApiComplianceIndigenousData
x-operation-id-source: derived
/api/compliance/india-sectoral-check:
post:
summary: Indian sectoral regulator applicability (RBI/SEBI/IRDAI/TRAI/PFRDA)
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: Sectoral matches
operationId: postApiComplianceIndiaSectoralCheck
x-operation-id-source: derived
/api/compliance/india-cross-border-countries:
get:
summary: DPDP §16 cross-border destination country registry
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
- name: country
in: query
schema:
type: string
responses:
'200':
description: Country registry
operationId: getApiComplianceIndiaCrossBorderCountries
x-operation-id-source: derived
/api/compliance/ca-province-matrix:
get:
summary: Canadian provincial privacy law matrix (PIPEDA + Loi 25 + Alberta/BC PIPA +…
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
- name: province
in: query
schema:
type: string
responses:
'200':
description: Matrix
operationId: getApiComplianceCaProvinceMatrix
x-operation-id-source: derived
/api/compliance/quebec-law25:
get:
summary: Per-operator Quebec Law 25 (Loi 25) readiness scorecard
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the grievance officer row says configured or pending, and where it names the officer it prints "[officer name - visible when signed in]" and "[officer email - visible when signed in]" instead. The signed-in owner sees the officer''s name and address.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiComplianceQuebecLaw25
x-operation-id-source: derived
/api/compliance/soc2-readiness:
get:
summary: SOC 2 Trust Service Criteria readiness scorecard (pre-audit)
tags:
- Compliance
security:
- Session: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiComplianceSoc2Readiness
x-operation-id-source: derived
/api/compliance/appi-readiness:
get:
summary: Japan APPI readiness scorecard (Art 17/18/21/23/26/28/30/35/40)
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the grievance officer row says configured or pending, and where it names the officer it prints "[officer name - visible when signed in]" and "[officer email - visible when signed in]" instead. The signed-in owner sees the officer''s name and address.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiComplianceAppiReadiness
x-operation-id-source: derived
/api/compliance/ndpa-readiness:
get:
summary: Nigeria NDPA 2023 readiness scorecard (§24/25/26/27/28/32/33/40/41)
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the grievance officer row says configured or pending, and where it names the officer it prints "[officer name - visible when signed in]" and "[officer email - visible when signed in]" instead. The signed-in owner sees the officer''s name and address.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiComplianceNdpaReadiness
x-operation-id-source: derived
/api/compliance/ai-act-classify:
post:
summary: EU AI Act risk classifier (prohibited / high-risk / limited / minimal + GPAI…
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: Classification
operationId: postApiComplianceAiActClassify
x-operation-id-source: derived
/api/compliance/dsa-status:
post:
summary: EU Digital Services Act applicability (intermediary / hosting / online platform…
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: DSA tier
operationId: postApiComplianceDsaStatus
x-operation-id-source: derived
/api/compliance/japan-cross-border:
get:
summary: Japan APPI Art 28 cross-border country registry
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
- name: country
in: query
schema:
type: string
responses:
'200':
description: Registry
operationId: getApiComplianceJapanCrossBorder
x-operation-id-source: derived
/api/compliance/global-status:
get:
summary: Master endpoint listing every privacy/security/sectoral regime VITNA covers
tags:
- Compliance
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Global status
operationId: getApiComplianceGlobalStatus
x-operation-id-source: derived
/api/compliance/hipaa-readiness:
get:
summary: 'Withdrawn: the HIPAA Business Associate readiness scorecard'
description: 'Withdrawn on 2026-11-01. COSTRINITY signs no Business Associate Agreement and has none with its providers, and VITNA is not for protected health information: do not send PHI. Answers 410 {error: "withdrawn", note} to anyone.'
tags:
- Compliance
responses:
'410':
description: withdrawn
operationId: getApiComplianceHipaaReadiness
x-operation-id-source: derived
/api/compliance/iso27001-readiness:
get:
summary: ISO/IEC 27001:2022 Annex A readiness (22 controls evaluated)
tags:
- Compliance
security:
- Session: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiComplianceIso27001Readiness
x-operation-id-source: derived
/api/compliance/pci-dss-readiness:
get:
summary: PCI DSS v4.0 readiness (12 requirements)
tags:
- Compliance
security:
- Session: []
responses:
'200':
description: Readiness
operationId: getApiCompliancePciDssReadiness
x-operation-id-source: derived
/api/compliance/uk-gdpr-readiness:
get:
summary: UK GDPR + DPA 2018 readiness
description: 'With an API key (x-vitna-key, x-vigil-key, x-api-key or Authorization: Bearer, a restricted trial key included, even beside a session cookie) the DPO row says configured or pending, and where it names the officer it prints "[officer name - visible when signed in]" instead. The signed-in owner sees the officer''s name.'
tags:
- Compliance
security:
- Session: []
- ApiKey: []
- Bearer: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiComplianceUkGdprReadiness
x-operation-id-source: derived
/api/compliance/pipa-kr-readiness:
get:
summary: South Korea PIPA readiness (24h breach window)
tags:
- Compliance
security:
- Session: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiCompliancePipaKrReadiness
x-operation-id-source: derived
/api/compliance/app-au-readiness:
get:
summary: Australia Privacy Act + 13 APPs readiness
tags:
- Compliance
security:
- Session: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiComplianceAppAuReadiness
x-operation-id-source: derived
/api/compliance/pipl-cn-readiness:
get:
summary: China PIPL readiness scorecard
tags:
- Compliance
security:
- Session: []
parameters:
- name: format
in: query
schema:
type: string
enum:
- json
- md
responses:
'200':
description: Readiness
operationId: getApiCompliancePiplCnReadiness
x-operation-id-source: derived
components:
securitySchemes:
ApiKey:
type: apiKey
in: header
name: x-vigil-key
description: 'Per-agent API key. Format: vitna_<64-char-hex>; legacy vigil_ keys remain valid. Send on /api/ingest.'
Bearer:
type: http
scheme: bearer
bearerFormat: vitna_<key> (legacy vigil_<key> accepted)
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 a sign-in: the second step of a password sign-in (/api/auth/verify-pin), or, for an address whose mail Google handles (Gmail or a Google Workspace domain) while VITNA''s mail cannot reach Gmail, the password alone (/api/owners); GitHub; a passkey; or a claim.'
CronSecret:
type: http
scheme: bearer
description: Bearer ${CRON_SECRET}. Only the Vercel cron infrastructure should hold this.