{
  "openapi": "3.1.0",
  "info": {
    "title": "Glosario y corpus de Samael Aun Weor API",
    "version": "1.2.0",
    "description": "Public read-only API for discussing and researching Spanish terms in the works of Samael Aun Weor. No authentication is required. Start with GET /api/context; it is the compact machine-readable counterpart advertised by a shared term page."
  },
  "servers": [{"url": "/"}],
  "paths": {
    "/api/context": {
      "get": {
        "operationId": "getTranslationContext",
        "summary": "Get a compact, cited evidence packet for discussing how to translate a term",
        "description": "Recommended starting point for AI assistants. Returns human-approved Vietnamese terminology when available, Spanish meaning and usage, verified original-language evidence when publication policy permits it, bibliography, and related terms. Output collections are deliberately bounded.",
        "parameters": [
          {"$ref": "#/components/parameters/query"},
          {"$ref": "#/components/parameters/termId"}
        ],
        "responses": {
          "200": {"$ref": "#/components/responses/JsonResponse"},
          "404": {"$ref": "#/components/responses/JsonResponse"}
        }
      }
    },
    "/api/term": {
      "get": {
        "operationId": "researchTerm",
        "summary": "Get a term's glossary research and corpus results in one call",
        "parameters": [
          {"$ref": "#/components/parameters/query"},
          {"$ref": "#/components/parameters/termId"},
          {"$ref": "#/components/parameters/mode"},
          {"$ref": "#/components/parameters/kind"},
          {"$ref": "#/components/parameters/sections"}
        ],
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    },
    "/api/glossary": {
      "get": {
        "operationId": "getGlossaryTerm",
        "summary": "Resolve a term and return definitions, summaries, related terms, and requested source sections",
        "parameters": [
          {"$ref": "#/components/parameters/query"},
          {"$ref": "#/components/parameters/termId"},
          {"$ref": "#/components/parameters/sections"}
        ],
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    },
    "/api/search": {
      "get": {
        "operationId": "searchCorpus",
        "summary": "Search the corpus and return grouped cited excerpts",
        "parameters": [
          {"$ref": "#/components/parameters/query"},
          {"$ref": "#/components/parameters/termId"},
          {"$ref": "#/components/parameters/mode"},
          {"$ref": "#/components/parameters/kind"},
          {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}}
        ],
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    },
    "/api/glossary/evidence": {
      "get": {
        "operationId": "getRelationEvidence",
        "summary": "Get cited paragraph evidence for a relationship between two glossary terms",
        "parameters": [
          {"name": "source", "in": "query", "required": true, "schema": {"type": "string"}},
          {"name": "target", "in": "query", "required": true, "schema": {"type": "string"}}
        ],
        "responses": {
          "200": {"$ref": "#/components/responses/JsonResponse"},
          "404": {"$ref": "#/components/responses/JsonResponse"}
        }
      }
    },
    "/api/source-reader": {
      "get": {
        "operationId": "getBibliographicalPdfDestination",
        "summary": "Resolve a bibliographical excerpt to its validated physical PDF page and OCR highlighting capability",
        "parameters": [
          {"name": "book_id", "in": "query", "required": true, "schema": {"type": "string"}},
          {"name": "volume", "in": "query", "schema": {"type": "integer", "minimum": 1, "default": 1}},
          {"name": "page", "in": "query", "required": true, "description": "Page stored by the source extraction", "schema": {"type": "integer", "minimum": 1}},
          {"name": "passage_id", "in": "query", "description": "Stable passage identifier used for validated page repairs", "schema": {"type": "string"}},
          {"name": "q", "in": "query", "description": "Term to highlight when the PDF text layer is reliable", "schema": {"type": "string"}},
          {"name": "form", "in": "query", "description": "Additional attested spelling; may be repeated", "schema": {"type": "array", "items": {"type": "string"}}}
        ],
        "responses": {
          "200": {"$ref": "#/components/responses/JsonResponse"},
          "404": {"description": "Unknown or unavailable source PDF"}
        }
      }
    },
    "/api/original-passages": {
      "get": {
        "operationId": "getOriginalLanguagePassages",
        "summary": "Get policy-approved verified original-language passages for a term or aligned Spanish source paragraph",
        "parameters": [
          {"$ref": "#/components/parameters/query"},
          {"$ref": "#/components/parameters/termId"},
          {"name": "book_id", "in": "query", "schema": {"type": "string"}},
          {"name": "spanish_paragraph_id", "in": "query", "schema": {"type": "string"}},
          {"name": "context", "in": "query", "description": "Context paragraphs on each side, capped by source policy", "schema": {"type": "integer", "minimum": 0, "maximum": 5, "default": 0}}
        ],
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    },
    "/api/original/docs": {
      "get": {
        "operationId": "listOriginalDocuments",
        "summary": "List original-language witnesses approved for complete public reading",
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    },
    "/api/original/doc/{book_id}": {
      "get": {
        "operationId": "getOriginalDocument",
        "summary": "Get a complete policy-approved original-language witness",
        "parameters": [{"name": "book_id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {
          "200": {"$ref": "#/components/responses/JsonResponse"},
          "404": {"$ref": "#/components/responses/JsonResponse"}
        }
      }
    },
    "/api/original/search": {
      "get": {
        "operationId": "searchOriginalDocuments",
        "summary": "Full-text search across complete policy-approved original-language witnesses",
        "parameters": [
          {"name": "q", "in": "query", "required": true, "schema": {"type": "string"}},
          {"name": "book_id", "in": "query", "schema": {"type": "string"}},
          {"name": "offset", "in": "query", "schema": {"type": "integer", "minimum": 0, "default": 0}}
        ],
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    },
    "/api/doc/{doc_id}": {
      "get": {
        "operationId": "getDocument",
        "summary": "Get a complete work as structured headings and paragraphs",
        "parameters": [{"name": "doc_id", "in": "path", "required": true, "schema": {"type": "string"}}],
        "responses": {
          "200": {"$ref": "#/components/responses/JsonResponse"},
          "404": {"$ref": "#/components/responses/JsonResponse"}
        }
      }
    },
    "/api/docs": {
      "get": {
        "operationId": "listDocuments",
        "summary": "List all searchable works",
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    },
    "/api/stats": {
      "get": {
        "operationId": "getCorpusStats",
        "summary": "Get corpus counts",
        "responses": {"200": {"$ref": "#/components/responses/JsonResponse"}}
      }
    }
  },
  "components": {
    "parameters": {
      "query": {"name": "q", "in": "query", "description": "Spanish term or phrase", "schema": {"type": "string"}},
      "termId": {"name": "term_id", "in": "query", "description": "Stable glossary term ID, when known", "schema": {"type": "string"}},
      "mode": {"name": "mode", "in": "query", "schema": {"type": "string", "enum": ["lemma", "exact", "folded", "stem"], "default": "lemma"}},
      "kind": {"name": "kind", "in": "query", "schema": {"type": "string", "enum": ["samael", "book", "lecture", "source", "all"], "default": "samael"}},
      "sections": {"name": "sections", "in": "query", "description": "Comma-separated glossary sections. Default: summary,definitions,thesaurus. Optional: theosophical_glossary,gurdjieff,biblical_background,dioses_atomicos,external_sources,original_language_passages", "schema": {"type": "string", "default": "summary,definitions,thesaurus"}}
    },
    "responses": {
      "JsonResponse": {
        "description": "JSON result; field shapes are stable and self-describing",
        "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}
      }
    }
  }
}