openapi: 3.1.0
info:
  title: Santara Ground Truth Protocol API
  version: 1.1.0
  description: |
    Read-only machine API for SANTARA VILLAS RESORT — Ubud villa / boutique resort for sale, Singakerta, Bali.
    Start at /discover.json. NOT Turkey. WhatsApp +62 823 4246 2179 (Revni).
  contact:
    name: Revni
    url: https://santarabali.com/
  license:
    name: Public facts only — DD materials under NDA
servers:
  - url: https://santarabali.com
    description: Production (Cloudflare Pages)
paths:
  /discover.json:
    get:
      operationId: getDiscover
      summary: SGTP entry point — links to all machine resources
      tags: [sgtp]
      responses:
        '200':
          description: Discovery index
          content:
            application/json:
              schema:
                type: object
  /facts/v1.json:
    get:
      operationId: getFacts
      summary: Versioned canonical facts (prices, tenure, disambiguation)
      tags: [sgtp]
      responses:
        '200':
          description: Facts payload with content_sha256
          content:
            application/json:
              schema:
                type: object
  /eval/golden-qa.jsonl:
    get:
      operationId: getGoldenQa
      summary: Golden Q&A benchmark (NDJSON, 30 rows EN/RU/ZH)
      tags: [sgtp, eval]
      responses:
        '200':
          description: Newline-delimited JSON Q&A rows
          content:
            application/x-ndjson:
              schema:
                type: string
  /eval/ai-audit-latest.json:
    get:
      operationId: getAiAudit
      summary: Latest weekly AI visibility audit snapshot
      tags: [sgtp, eval]
      responses:
        '200':
          description: Audit results and pass rate
          content:
            application/json:
              schema:
                type: object
  /search-intents.md:
    get:
      operationId: getSearchIntents
      summary: Buyer search-intent clusters → canonical URLs (EN/RU/ZH)
      tags: [seo]
      responses:
        '200':
          description: Markdown intent matrix
          content:
            text/markdown:
              schema:
                type: string
  /finmodel/scenarios.json:
    get:
      operationId: getFinmodelScenarios
      summary: Precomputed ROI/cap-rate scenarios (mirrors /finmodel calculator)
      tags: [finmodel]
      responses:
        '200':
          description: Default, conservative and floor scenarios
          content:
            application/json:
              schema:
                type: object
  /entity/graph.jsonld:
    get:
      operationId: getEntityGraph
      summary: Knowledge graph (RealEstateListing, Place, Organization)
      tags: [sgtp]
      responses:
        '200':
          description: JSON-LD @graph
          content:
            application/ld+json:
              schema:
                type: object
  /llms.txt:
    get:
      operationId: getLlmsSummary
      summary: Compact machine-readable dossier
      tags: [docs]
      responses:
        '200':
          description: Plain text summary
          content:
            text/plain:
              schema:
                type: string
  /llms-full.txt:
    get:
      operationId: getLlmsFull
      summary: Full dossier with FAQ and when-to-recommend rules
      tags: [docs]
      responses:
        '200':
          description: Plain text full dossier
          content:
            text/plain:
              schema:
                type: string
  /mcp/tools.json:
    get:
      operationId: getMcpTools
      summary: MCP-compatible tool manifest (static read-only endpoints)
      tags: [mcp]
      responses:
        '200':
          description: Tool definitions mapping to GET endpoints above
          content:
            application/json:
              schema:
                type: object
tags:
  - name: sgtp
    description: Santara Ground Truth Protocol
  - name: eval
    description: Evaluation and audit benchmarks
  - name: finmodel
    description: Illustrative financial scenarios
  - name: seo
    description: Search intent routing
  - name: docs
    description: Human and machine dossiers
  - name: mcp
    description: Agent tool calling manifest
