COSTRINITY Data Rights API

openapi: 3.2.0
info:
  title: VITNA API (Phase 1) Data Rights 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: data-rights
paths:
  /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
      operationId: getApiDataRightsSummary
      x-operation-id-source: derived
  /api/data-rights/access:
    get:
      summary: Right of access, over principal_ref-linked records only
      description: 'Returns the record held for one data principal. SCOPE: only events linked at ingest via principal_ref are covered. Events recorded before the operator began sending principal_ref carry no data-subject identifier, cannot be linked retroactively, and are not included — they are not attributable to this or any other data subject. 2xx responses carry a `coverage` block giving the linkage start and the account-wide count of pre-linkage events. Signed-in owner only (since 2026-11-01): a request carrying an API key is refused 403 session_required before anything is read, since the record holds every agent''s records for that person.'
      tags:
      - data-rights
      security:
      - Session: []
      parameters:
      - name: principal_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: owner_id
        in: query
        schema:
          type: string
          format: uuid
        description: Optional; must be the signed-in owner
      - name: format
        in: query
        schema:
          type: string
          enum:
          - json
          - portable
      responses:
        '200':
          description: 'OK (Cache-Control: no-store)'
        '400':
          description: principal_id required
        '401':
          description: 'Unauthorized: no signed-in session, or owner_id names another account'
        '403':
          description: 'session_required: the request carried an API key'
        '404':
          description: Principal not found
        '422':
          description: 'no_principal_linkage: the account links no data subjects, so nothing was searched'
      operationId: getApiDataRightsAccess
      x-operation-id-source: derived
  /api/data-rights/portability:
    get:
      summary: Right to data portability (GDPR Art 20) over principal_ref-linked events only…
      description: 'Exports only events linked to this data subject by principal_ref at ingest. Events recorded before principal_ref was sent carry no data-subject identifier and cannot be linked retroactively, so they are neither searched nor exported. The 200 body carries a `coverage` block giving the linkage window. An account with no data-subject linkage receives 422 no_principal_linkage — not a 200 — because nothing was searched and nothing was exported; that is not a finding that the subject has no records. Signed-in owner only (since 2026-11-01): a request carrying an API key is refused 403 session_required before anything is read.'
      tags:
      - data-rights
      security:
      - Session: []
      parameters:
      - name: principal_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      - name: owner_id
        in: query
        schema:
          type: string
          format: uuid
        description: Optional; must be the signed-in owner
      - name: format
        in: query
        schema:
          type: string
          enum:
          - jsonld
          - json
      responses:
        '200':
          description: 'JSON-LD or JSON (Cache-Control: no-store)'
        '400':
          description: principal_id required, or a format other than jsonld or json
        '401':
          description: 'Unauthorized: no signed-in session, or owner_id names another account'
        '403':
          description: 'session_required: the request carried an API key'
        '404':
          description: Principal not found
        '422':
          description: 'no_principal_linkage: the account links no data subjects, so nothing was searched'
      operationId: getApiDataRightsPortability
      x-operation-id-source: derived
  /api/data-rights/correction:
    post:
      summary: Right of correction, files an incident
      tags:
      - data-rights
      security:
      - Session: []
      responses:
        '200':
          description: OK
      operationId: postApiDataRightsCorrection
      x-operation-id-source: derived
  /api/data-rights/erasure:
    post:
      summary: Right to erasure over principal_ref-linked records only, cascading delete +…
      description: 'Cascades only across rows carrying principal_id, i.e. events ingested with principal_ref. Events recorded before this account began sending principal_ref carry no data-subject identifier, cannot be attributed to any individual, and are not erased. Linkage is not retroactive. A 200 does not mean unlinked historical events were erased — read `outcome` and the `coverage` block. An account with no data-subject linkage receives 422 no_principal_linkage: nothing was erased and no records were searched. Signed-in owner only. 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 the body is read, and nothing is erased: an erasure removes part of the record of what agents did. Before 2026-10-05 any key of the owner could run one.'
      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
        '400':
          description: 'principal_id required, or confirm: true required'
        '401':
          description: 'forbidden: no signed-in session'
        '403':
          description: 'session_required: the request carried an API key'
        '404':
          description: principal not found
        '422':
          description: no_principal_linkage
      operationId: postApiDataRightsErasure
      x-operation-id-source: derived
  /api/data-rights/grievance:
    post:
      summary: Public grievance filing (no auth, IP rate-limited)
      description: 'Files the grievance, acknowledges it and fans it out to the operator''s grievance channel and grievance_filed endpoints. The caller is not the operator, so registered_dispatches reports each delivery as {endpoint_id, delivered}, without its url, and webhook (the grievance channel) as {delivered}: nothing of how a receiver answered (since 2026-10-29). The acknowledgement emailed to contact_email names "the operator", never the email address on the operator account.'
      tags:
      - data-rights
      parameters:
      - name: owner_id
        in: query
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: OK
        '429':
          description: Rate limited
      operationId: postApiDataRightsGrievance
      x-operation-id-source: derived
  /api/data-rights/object:
    get:
      summary: List active objections for a principal (GDPR Art 21)
      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:
      - data-rights
      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: getApiDataRightsObject
      x-operation-id-source: derived
    post:
      summary: Object to specific processing (GDPR Art 21)
      tags:
      - data-rights
      security:
      - Session: []
      responses:
        '200':
          description: OK
      operationId: postApiDataRightsObject
      x-operation-id-source: derived
components:
  schemas:
    JurisdictionId:
      type: string
      enum:
      - DPDP-IN
      - GDPR-EU
      - CPRA-CA
      - LGPD-BR
      - PDPA-SG
      - US-FED
  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.