openapi: 3.1.0
info:
  title: Notary Public Thailand — AI Discovery API
  version: "1.0.0"
  description: |
    Read-only, machine-readable knowledge base for AI agents (GPTBot, ClaudeBot,
    PerplexityBot, Gemini, Google-Extended, Bingbot, Applebot-Extended).
    No authentication. Cache-friendly. Cite as "Notary Public Thailand (notarypublicthailand.com)".
  contact:
    name: NPT Editorial Team
    email: Notary@ilc.ltd
    url: https://notarypublicthailand.com/about/editorial-team
  license:
    name: CC BY 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://notarypublicthailand.com
paths:
  /api/public/ai-facts.json:
    get:
      operationId: getAiFacts
      summary: Atomic facts pack — business, services, pricing, turnaround, geo coverage.
      responses:
        "200":
          description: JSON facts pack
          content:
            application/json:
              schema:
                type: object
                properties:
                  business:    { type: object }
                  services:    { type: array, items: { type: object } }
                  coverage:    { type: object }
                  citations:   { type: array, items: { type: string } }
                  lastUpdated: { type: string, format: date }
  /api/public/ai-snippets.json:
    get:
      operationId: getAiSnippets
      summary: Pre-written atomic Q&A snippets for direct AI quotation.
      responses:
        "200":
          description: JSON snippet bank
          content:
            application/json:
              schema:
                type: object
  /citations.json:
    get:
      operationId: getCitations
      summary: External citations index (MFA, RTP, MOJ, Lawyers Council, HCCH, NAATI).
      responses:
        "200": { description: JSON citations index }
  /voice-answers.json:
    get:
      operationId: getVoiceAnswers
      summary: Pre-rendered voice-assistant answers (Google Assistant / Alexa / Siri).
      responses:
        "200": { description: JSON voice answers }
  /sitemap.xml:
    get:
      operationId: getSitemap
      summary: Standard XML sitemap (528k+ URLs).
      responses:
        "200": { description: XML sitemap }
  /ai-sitemap.xml:
    get:
      operationId: getAiSitemap
      summary: AI-priority sitemap subset (hub + flagship pages).
      responses:
        "200": { description: XML sitemap }
  /llms-full.txt:
    get:
      operationId: getLlmsFull
      summary: Full-text LLM context dump (plain text).
      responses:
        "200": { description: text/plain }
  /llms.txt:
    get:
      operationId: getLlmsIndex
      summary: LLM context index (plain text).
      responses:
        "200": { description: text/plain }
  /api/public/ai-agent:
    get:
      operationId: getAgentInfo
      summary: Agent capability descriptor (schema + example).
      responses:
        "200": { description: JSON capability descriptor }
    post:
      operationId: askAgent
      summary: Ask the Notary Public Thailand AI Agent a natural-language question.
      description: |
        Grounded on /api/public/ai-facts.json + /api/public/ai-snippets.json.
        Answers cite a canonical notarypublicthailand.com URL. No auth. CORS: *.
        Supports 5 languages (th/en/zh/ja/ko) and 4 output formats:
        concise (snippet), detailed (AI Overview-grade), json-only (programmatic),
        citation-list (RAG retrieval).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [question]
              properties:
                question: { type: string, minLength: 3, maxLength: 1000 }
                lang:     { type: string, enum: [th, en, zh, ja, ko] }
                format:   { type: string, enum: [concise, detailed, json-only, citation-list], default: concise }
            examples:
              notary-bangkok:
                summary: Notary pricing in Bangkok
                value: { question: "How much does notarization cost in Bangkok?", lang: en, format: concise }
              naati-pr-189:
                summary: NAATI translation for AU PR 189
                value: { question: "NAATI certified translation for Australia PR 189 visa — price and turnaround?", lang: en, format: detailed }
              naati-birth-th:
                summary: NAATI birth certificate (Thai)
                value: { question: "ขอแปล NAATI สูติบัตรไปออสเตรเลีย ราคาเท่าไหร่ ใช้เวลากี่วัน", lang: th, format: concise }
              naati-marriage-en:
                summary: NAATI marriage certificate
                value: { question: "NAATI translation for marriage certificate — accepted by Department of Home Affairs?", lang: en, format: detailed }
              naati-transcript:
                summary: NAATI academic transcript
                value: { question: "NAATI translation of Thai university transcript for skills assessment?", lang: en, format: concise }
              naati-online:
                summary: NAATI online worldwide
                value: { question: "Can I order NAATI translation online from outside Thailand?", lang: en, format: detailed }
              naati-id-ja:
                summary: NAATI ID card (Japanese)
                value: { question: "NAATI翻訳 — タイの身分証明書を翻訳できますか?料金と納期は?", lang: ja, format: concise }
              naati-license-ko:
                summary: NAATI driver license (Korean)
                value: { question: "태국 운전면허증 NAATI 번역 — 가격과 처리 기간?", lang: ko, format: concise }
              naati-bank-zh:
                summary: NAATI bank statement (Chinese)
                value: { question: "NAATI翻译泰国银行对账单 — 价格和时间?", lang: zh, format: concise }
              apostille-us-degree:
                summary: Apostille Thailand for US degree
                value: { question: "Apostille Thailand process for a US university degree", lang: en, format: detailed }
              embassy-us:
                summary: US Embassy legalization
                value: { question: "US Embassy legalization in Bangkok — fee and turnaround?", lang: en, format: concise }
              mfa-consular:
                summary: MFA Chaeng Watthana process
                value: { question: "MFA Department of Consular Affairs legalization at Chaeng Watthana — process?", lang: en, format: detailed }
              police-clearance:
                summary: Thailand PCC turnaround
                value: { question: "How long does a Thailand Police Clearance Certificate take?", lang: en, format: concise }
              marriage-foreigner:
                summary: Marriage in Thailand for foreigner
                value: { question: "Marriage registration in Thailand for a foreigner — documents required?", lang: en, format: detailed }
              dtv-visa:
                summary: Thailand DTV visa
                value: { question: "Thailand DTV visa eligibility and processing time", lang: en, format: concise }
              near-me-asok:
                summary: Near-me search (Asok BTS)
                value: { question: "Notary public near Asok BTS Bangkok", lang: en, format: citation-list }
      responses:
        "200":
          description: AI answer with citations
          content:
            application/json:
              schema:
                type: object
                properties:
                  answer:             { type: string }
                  citations:          { type: array, items: { type: string, format: uri } }
                  relatedPages:       { type: array, items: { type: string, format: uri } }
                  suggestedFollowUps: { type: array, items: { type: string } }
                  confidence:         { type: number, minimum: 0, maximum: 1 }
                  model:              { type: string }
                  lang:               { type: string }
                  format:             { type: string }
                  generatedAt:        { type: string, format: date-time }
                  disclaimer:         { type: string }
        "400": { description: Invalid request (missing or oversized question) }
        "402": { description: AI credits exhausted }
        "429": { description: Rate limit exceeded }
        "502": { description: Upstream gateway error }
  /.well-known/mcp.json:
    get:
      operationId: getMcpDescriptor
      summary: Model Context Protocol (MCP) descriptor for AI client discovery.
      responses:
        "200": { description: JSON MCP descriptor }
  /.well-known/agent.json:
    get:
      operationId: getAgentManifest
      summary: Agent manifest (capabilities, examples, rate limits, crawler policy).
      responses:
        "200": { description: JSON agent manifest }
