{
  "openapi": "3.0.3",
  "info": {
    "title": "Bible Study API",
    "description": "Exposes structured Bible study payloads for original-language syntax, variants, witnesses, trajectories, relationship graphs, and annotations.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://bible.grod.es"
    }
  ],
  "paths": {
    "/openapi.json": {
      "get": {
        "summary": "This OpenAPI specification",
        "description": "Returns the complete OpenAPI definition representing all GET-centric HTTP study endpoints.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    },
    "/healthz": {
      "get": {
        "summary": "Health status",
        "description": "Exposes health check status confirming database reachability and service health.",
        "responses": {
          "200": {
            "description": "Healthy"
          },
          "503": {
            "description": "Unhealthy"
          }
        }
      }
    },
    "/api/stats": {
      "get": {
        "summary": "Database table row counts",
        "description": "Returns a map of all database table names and their respective live row counts.",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/skill": {
      "get": {
        "summary": "Markdown Study Skill guide",
        "description": "Returns the canon instruction manual for the Bible Study AI workflow.",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "text/markdown": {}
            }
          }
        }
      }
    },
    "/api/tools": {
      "get": {
        "summary": "Available tools list",
        "description": "Returns the list of supported bible study commands/tools.",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/sources": {
      "get": {
        "summary": "Database source coverage",
        "description": "Returns details of the database's live source provenance, table lineage, and cautions.",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/coverage": {
      "get": {
        "summary": "Dynamic data coverage check",
        "description": "Returns dynamic field coverage categories for a reference.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Bible reference.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "standard": {
                "value": "Jer 7:31"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/strong": {
      "get": {
        "summary": "Strong's lexicon entry",
        "description": "Look up definitions, glosses, derivations, and transliteration for a Hebrew/Greek Strong key.",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Strong key or numeric ID. Hebrew keys must start with H; Greek with G. Bare numbers are parsed as Hebrew.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "h5414": {
                "summary": "Standard Hebrew Strong Key",
                "value": "H5414"
              },
              "h1060": {
                "summary": "Second Hebrew Example",
                "value": "H1060"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/search-strong": {
      "get": {
        "summary": "Search Strong occurrences",
        "description": "Search occurrences of a Strong number across all verses in the corpus.",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Strong's key (e.g. H5414 or G3056).",
            "schema": {
              "type": "string"
            },
            "examples": {
              "hebrew_key": {
                "value": "H5414"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of rows to return.",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/word-study": {
      "get": {
        "summary": "Word study analysis",
        "description": "Alias to search strong. Search occurrences of a Strong number in the corpus.",
        "parameters": [
          {
            "name": "key",
            "in": "query",
            "required": true,
            "description": "Strong's key.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "hebrew_key": {
                "value": "H5414"
              }
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of rows to return.",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/phrase": {
      "get": {
        "summary": "Search phrase match tokens",
        "description": "Search for specific Strong-based phrase matches within a single verse.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Bible verse reference.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "standard": {
                "value": "Exod 22:28"
              }
            }
          },
          {
            "name": "words",
            "in": "query",
            "required": true,
            "description": "Comma-separated list of Strong keys expected to match.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "standard": {
                "value": "H5414,H0853"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/analyze": {
      "get": {
        "summary": "Unified structured verse or passage study",
        "description": "High-level unified analysis. Autodetects if reference is a single verse, chapter, book or inclusive passage range.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Reference string. Supports verses, chapters, books, and inclusive passage ranges.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "exod2228": {
                "summary": "Exod 22:28",
                "value": "Exod 22:28"
              },
              "exod13": {
                "summary": "Exod 13",
                "value": "Exod 13"
              },
              "jer731": {
                "summary": "Jer 7:31",
                "value": "Jer 7:31"
              },
              "ezek202526": {
                "summary": "Ezek 20:25-26",
                "value": "Ezek 20:25-26"
              },
              "john753": {
                "summary": "John 7:53-8:11",
                "value": "John 7:53-8:11"
              },
              "mark169": {
                "summary": "Mark 16:9-20",
                "value": "Mark 16:9-20"
              },
              "deut328": {
                "summary": "Deut 32:8",
                "value": "Deut 32:8"
              },
              "ps2216": {
                "summary": "Ps 22:16",
                "value": "Ps 22:16"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/passage": {
      "get": {
        "summary": "Passage range analysis",
        "description": "Detailed aggregated analysis of an inclusive same-book passage range.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Passage reference range.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "ezek": {
                "value": "Ezek 20:25-26"
              },
              "john": {
                "value": "John 7:53-8:11"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/chapter": {
      "get": {
        "summary": "Chapter analysis",
        "description": "Aggregated critical, lexical, and historical analysis of a single chapter.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Chapter reference.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "exod13": {
                "value": "Exod 13"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/book": {
      "get": {
        "summary": "Book analysis",
        "description": "Aggregated book-level statistics, key terms, witnesses, and variants.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Full book name or recognized abbreviation.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "exod": {
                "value": "Exod"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/witnesses": {
      "get": {
        "summary": "Witnesses details",
        "description": "Get ancient aligned manuscripts and witnesses details for a verse.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Verse reference.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "deut328": {
                "value": "Deut 32:8"
              },
              "ps2216": {
                "value": "Ps 22:16"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/variants": {
      "get": {
        "summary": "Textual variants",
        "description": "Retrieve prioritized textual variants and candidate apparatus data.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Verse reference.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "mark169": {
                "value": "Mark 16:9-20"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/trajectory": {
      "get": {
        "summary": "Trajectory trace",
        "description": "Sequentially load and return study payloads for comma-separated list of refs.",
        "parameters": [
          {
            "name": "refs",
            "in": "query",
            "required": true,
            "description": "Comma-separated list of refs.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "trajectory_ex": {
                "value": "Exod 22:28,Exod 13"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/api/evidence-graph": {
      "get": {
        "summary": "Relationship evidence graph",
        "description": "Returns Nodes and Edges based on study payloads for provided refs.",
        "parameters": [
          {
            "name": "refs",
            "in": "query",
            "required": true,
            "description": "Comma-separated list of refs.",
            "schema": {
              "type": "string"
            },
            "examples": {
              "graph_ex": {
                "value": "Exod 22:28,Jer 7:31"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "Unified MCP JSON-RPC protocol over HTTP",
        "description": "Standard Model Context Protocol JSON-RPC handler mapping JSON tools to Go functions.",
        "responses": {
          "200": {
            "description": "Success"
          }
        }
      }
    }
  }
}