openapi: 3.1.0
info:
  title: iVC Public Knowledge API
  description: |
    Read-only public endpoints exposing iVC's service catalog, coverage
    statistics, and machine-readable knowledge artifacts for AI engines,
    journalists, and research tools. No authentication required.
  version: "1.0.0"
  contact:
    name: iVC
    email: contact@ivc.ltd
    url: https://www.ivc.ltd
  license:
    name: CC-BY-4.0 (with required attribution)
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://www.ivc.ltd
    description: Production
paths:
  /api/public/stats.json:
    get:
      operationId: getStats
      summary: Aggregate operational statistics
      description: Returns approved-case count, success rate, country coverage, languages supported, customer rating, and review count.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  approvedVisas: { type: integer, example: 30000 }
                  successRate:   { type: number,  example: 99.8 }
                  countriesServed: { type: integer, example: 195 }
                  provincesServed: { type: integer, example: 77 }
                  languagesSupported: { type: integer, example: 120 }
                  customerRating: { type: number, example: 4.9 }
                  totalReviews: { type: integer, example: 8168 }
                  lastUpdated: { type: string, format: date }
  /services-knowledge.json:
    get:
      operationId: getServicesKnowledge
      summary: Full service catalog (JSON-LD Dataset)
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /methods.json:
    get:
      operationId: getMethodology
      summary: Methodology, E-E-A-T, refund policy, data handling
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /entity-graph.json:
    get:
      operationId: getEntityGraph
      summary: Organization + Place + Dataset entity graph
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /claim-review.json:
    get:
      operationId: getClaimReviews
      summary: Verified ClaimReview statements
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /llms-full.txt:
    get:
      operationId: getLLMsFull
      summary: Full LLM knowledge document (markdown)
      responses:
        "200": { description: OK, content: { text/plain: { schema: { type: string } } } }
