openapi: 3.1.0
info:
  title: Klarify Compliance Status API
  version: '2026-06-18'
  description: |
    Founder-authorised compliance posture snapshots for investors, accelerators,
    and bank innovation teams. Requires a valid investor share token created in
    Klarify FundRaise Mode (Compass+). Self-assessment — not legal advice.
servers:
  - url: https://api.klarify.africa
paths:
  /api/v1/compliance-status/{token}:
    get:
      summary: Get compliance status snapshot
      operationId: getComplianceStatus
      parameters:
        - name: token
          in: path
          required: true
          schema:
            type: string
          description: Investor share token from FundRaise Mode
      responses:
        '200':
          description: Active snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComplianceStatusEnvelope'
        '404':
          description: Token not found or revoked
        '410':
          description: Token expired
        '429':
          description: Rate limited (60 req/min per IP)
components:
  schemas:
    ComplianceStatusEnvelope:
      type: object
      required: [success, data, meta]
      properties:
        success:
          type: boolean
          enum: [true]
        data:
          $ref: '#/components/schemas/ComplianceStatusSnapshot'
        meta:
          type: object
          properties:
            token_status:
              type: string
              enum: [active]
            view_count:
              type: integer
    ComplianceStatusSnapshot:
      type: object
      properties:
        api_version:
          type: string
          example: '2026-06-18'
        company:
          type: object
          properties:
            name:
              type: string
        scores:
          type: object
          properties:
            readiness_score:
              type: integer
              minimum: 0
              maximum: 100
            readiness_label:
              type: string
            fundraise_score:
              type: integer
            fundraise_risk_band:
              type: string
            checklist_completion_pct:
              type: integer
        licensing:
          type: object
        verification:
          type: object
        top_gaps:
          type: array
          maxItems: 3
        links:
          type: object
        disclaimer:
          type: string
