openapi: 3.0.3
info:
  title: ProveIQ Core API
  version: v1.0.0
  description: |
    Public and partner-facing surface for the ProveIQ verification platform.
    API-first per Constitution §2.3 and Exit-Readiness Mandate 1.

    Auth: session cookie (for /api/me/*) or scoped API key (for /api/v1/*).
    Rate limits: 60 req/min per user, 600 req/min per API key.
servers:
  - url: https://proveiq.in
    description: Production

paths:
  /api/public/agreement-rate:
    get:
      summary: Global AI-Employer Agreement Rate (public)
      description: Rolling 90-day aggregate. No auth. No PII.
      tags: [Public, Metrics]
      responses:
        '200':
          description: Current rate
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AgreementRate' }

  /api/v1/playbooks/generate:
    post:
      summary: AI Pillar 1 — Generate DIY playbook from brief
      tags: [AI Pillars]
      security: [{ apiKey: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PlaybookBrief' }
      responses:
        '200':
          description: Structured playbook
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Playbook' }

  /api/v1/integrity/check:
    post:
      summary: AI Pillar 3 — Submission integrity score
      tags: [AI Pillars]
      security: [{ apiKey: [] }]
      responses:
        '200':
          description: Integrity score + signals

  /api/rubrics/generate:
    post:
      summary: AI Pillar 4 — Extract structured rubric from unstructured brief
      tags: [AI Pillars]

  /api/dsr/access:
    get:
      summary: DPDP §3.1.4 — Download full user data export
      tags: [DSR]
      security: [{ cookieAuth: [] }]

  /api/dsr/correction:
    patch:
      summary: DPDP §3.1.4 — Correct user data
      tags: [DSR]

  /api/dsr/erasure:
    delete:
      summary: DPDP §3.1.4 — Hard cascading deletion
      tags: [DSR]

  /api/dsr/grievance:
    post:
      summary: DPDP §3.1.4 — File grievance with DPO
      tags: [DSR]

  /api/dsr/nomination:
    post:
      summary: DPDP §3.1.4 — Nominate representative
      tags: [DSR]

  /api/consent:
    post:
      summary: Grant or revoke per-purpose consent
      tags: [Consent]

  /api/submissions:
    post:
      summary: Submit work for a milestone
      tags: [Submissions]
    get:
      summary: List submissions (scoped to caller)
      tags: [Submissions]

  /api/evaluations/{id}/employer-rating:
    post:
      summary: Employer's independent rating of the same submission
      description: Primary PMF signal per Constitution §6.1.
      tags: [Evaluations]

  /api/verify/{certificateNo}:
    get:
      summary: Verify a ProveIQ certificate by number
      tags: [Certificates, Public]

  /api/leaderboard:
    get:
      summary: Public leaderboard by domain
      tags: [Public]

  /api/metrics/agreement-rate:
    get:
      summary: Admin/employer scoped Agreement Rate with per-domain breakdown
      tags: [Metrics]
      security: [{ cookieAuth: [] }]

components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
    apiKey:
      type: apiKey
      in: header
      name: X-ProveIQ-Key
  schemas:
    AgreementRate:
      type: object
      properties:
        agreementRate: { type: number, example: 82.3 }
        total: { type: integer, example: 237 }
        agreed: { type: integer, example: 195 }
        sampleAdequate: { type: boolean, example: true }
        windowDays: { type: integer, example: 90 }
        threshold: { type: number, example: 1.0 }
        updatedAt: { type: string, format: date-time }
    PlaybookBrief:
      type: object
      required: [title, deliverables, successCriteria, durationDays, domain]
      properties:
        title: { type: string }
        deliverables: { type: array, items: { type: string } }
        successCriteria: { type: array, items: { type: string } }
        durationDays: { type: integer }
        domain: { type: string }
    Playbook:
      type: object
      properties:
        milestones: { type: array, items: { $ref: '#/components/schemas/Milestone' } }
        rubric_preview: { type: object }
    Milestone:
      type: object
      properties:
        day: { type: integer }
        title: { type: string }
        tasks: { type: array, items: { type: string } }
        tutorial_links: { type: array, items: { type: string } }