COSTRINITY India API

openapi: 3.2.0
info:
  title: VITNA API (Phase 1) India 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: india
paths:
  /api/india/aadhaar-mask:
    post:
      summary: Mask + Verhoeff-validate an Aadhaar (server-side; no persistence)
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: Masked + reference token
      operationId: postApiIndiaAadhaarMask
      x-operation-id-source: derived
  /api/india/verhoeff-verify:
    post:
      summary: Verhoeff D5 checksum verification for 12-digit numbers (no persistence)
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: Validity
      operationId: postApiIndiaVerhoeffVerify
      x-operation-id-source: derived
  /api/india/pan-classify:
    post:
      summary: PAN entity-type classification from 4th character
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: Entity classification
      operationId: postApiIndiaPanClassify
      x-operation-id-source: derived
  /api/india/upi-validate:
    post:
      summary: UPI handle format + PSP recognition
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: UPI validation
      operationId: postApiIndiaUpiValidate
      x-operation-id-source: derived
  /api/india/gstn-validate:
    post:
      summary: GSTIN format + check-digit + state-code lookup
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: GSTIN validation
      operationId: postApiIndiaGstnValidate
      x-operation-id-source: derived
  /api/india/regulators:
    get:
      summary: Public directory of India sectoral regulators (RBI/SEBI/IRDAI/TRAI/etc.)
      tags:
      - india
      parameters:
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - md
      - name: sector
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Regulator directory
      operationId: getApiIndiaRegulators
      x-operation-id-source: derived
  /api/india/mobile-validate:
    post:
      summary: Indian mobile +91 format + operator/circle hint (MNP-caveated)
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: Validation result
      operationId: postApiIndiaMobileValidate
      x-operation-id-source: derived
  /api/india/ifsc-validate:
    post:
      summary: IFSC format + bank code recognition (~50 banks)
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: Validation result
      operationId: postApiIndiaIfscValidate
      x-operation-id-source: derived
  /api/india/pincode-validate:
    post:
      summary: PIN code format + region/state hint (India Post numbering plan)
      tags:
      - india
      security:
      - Session: []
      responses:
        '200':
          description: Validation result
      operationId: postApiIndiaPincodeValidate
      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.