openapi: 3.1.0
info:
  title: iVC Public Knowledge API
  description: |
    Read-only public endpoints exposing iVC's service catalog, coverage
    statistics, machine-readable knowledge artifacts, and the AI Agent
    Gateway v2.0 for AI engines (ChatGPT, Perplexity, Claude, Gemini, AI
    Overview, Bing Copilot, MCP clients), journalists, and research tools.
    No authentication required. License: CC-BY-4.0 with attribution to ivisa.co.th.
  version: "2.0.0"
  contact:
    name: iVC
    email: contact@ivc.ltd
    url: https://ivisa.co.th
  license:
    name: CC-BY-4.0 (with required attribution)
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://ivisa.co.th
    description: Production
tags:
  - name: ai-agent
    description: AI Agent Gateway v2.0 — single endpoint, op-dispatched, MCP-compatible.
  - name: knowledge
    description: Static machine-readable knowledge artifacts.
paths:
  /api/public/ai-agent:
    get:
      tags: [ai-agent]
      operationId: aiAgent
      summary: AI Agent Gateway (op-dispatched)
      description: |
        Unified gateway for AI engines and MCP clients. Use the `op` query
        parameter to route the request. Pass `lang` for localized labels.
        Send `Accept: application/x-ndjson` on `op=list` or `op=bulk` to
        receive line-delimited JSON.
      parameters:
        - in: query
          name: op
          description: Operation to invoke.
          schema:
            type: string
            enum: [capabilities, search, country, service, inbound, nationality, province, area, pricing, channels, fact, list, bulk]
        - in: query
          name: q
          description: Free-text query (for `search` and `area`).
          schema: { type: string }
        - in: query
          name: slug
          description: Resource slug (country/service/inbound/province).
          schema: { type: string }
        - in: query
          name: code
          description: ISO 3166-1 alpha-2 country code (for `nationality`).
          schema: { type: string }
        - in: query
          name: key
          description: Atomic fact key (for `fact`).
          schema: { type: string }
        - in: query
          name: type
          description: Collection type (for `list`).
          schema:
            type: string
            enum: [services, countries, nationalities, provinces, inbound, hubs, facts]
        - in: query
          name: keys
          description: "Comma-separated `kind:slug` pairs (for `bulk`)."
          schema: { type: string }
        - in: query
          name: service
          description: Service slug (for `pricing`).
          schema: { type: string }
        - in: query
          name: lang
          description: Response language.
          schema:
            type: string
            enum: [th, en, zh, ja, ko, ar]
      responses:
        "200":
          description: OK — JSON (or NDJSON when Accept allows).
          content:
            application/json:
              schema: { type: object }
            application/x-ndjson:
              schema: { type: string }
      x-mcp-tool: true
      x-mcp-manifest: https://ivisa.co.th/.well-known/mcp.json
    post:
      tags: [ai-agent]
      operationId: aiAgentPost
      summary: AI Agent Gateway (POST body)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [op]
              properties:
                op: { type: string }
                q: { type: string }
                slug: { type: string }
                code: { type: string }
                key: { type: string }
                type: { type: string }
                keys: { type: string }
                service: { type: string }
                lang: { type: string, enum: [th, en, zh, ja, ko, ar] }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { type: object }
      x-mcp-tool: true
  /.well-known/mcp.json:
    get:
      tags: [knowledge]
      operationId: getMcpManifest
      summary: MCP discovery manifest (13 tools)
      responses:
        "200": { description: OK, content: { application/json: { schema: { type: object } } } }
  /.well-known/ai-agent.json:
    get:
      tags: [knowledge]
      operationId: getAiAgentManifest
      summary: AI Agent discovery manifest
      responses:
        "200": { description: OK, content: { application/json: { schema: { type: object } } } }
  /services-knowledge.json:
    get:
      tags: [knowledge]
      operationId: getServicesKnowledge
      summary: Full service catalog (JSON-LD Dataset)
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /pricing-matrix.json:
    get:
      tags: [knowledge]
      operationId: getPricingMatrix
      summary: Indicative pricing matrix (THB)
      responses:
        "200": { description: OK, content: { application/json: { schema: { type: object } } } }
  /provinces-coverage.json:
    get:
      tags: [knowledge]
      operationId: getProvincesCoverage
      summary: 77 Thai provinces service coverage (Schema.org Dataset)
      responses:
        "200": { description: OK, content: { application/json: { schema: { type: object } } } }
  /service-area-nationwide.jsonld:
    get:
      tags: [knowledge]
      operationId: getServiceArea
      summary: Nationwide Service + areaServed JSON-LD
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /locations.jsonld:
    get:
      tags: [knowledge]
      operationId: getLocations
      summary: 14 LocalBusiness branches with GeoCoordinates
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /methods.json:
    get:
      tags: [knowledge]
      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:
      tags: [knowledge]
      operationId: getEntityGraph
      summary: Organization + Place + Dataset entity graph
      responses:
        "200": { description: OK, content: { application/ld+json: { schema: { type: object } } } }
  /llms-full.txt:
    get:
      tags: [knowledge]
      operationId: getLLMsFull
      summary: Full LLM knowledge document (markdown)
      responses:
        "200": { description: OK, content: { text/plain: { schema: { type: string } } } }