{
  "openapi": "3.0.0",
  "info": {
    "title": "Tanach Search API",
    "version": "1.0.0",
    "description": "API for searching the Tanach (Hebrew Bible) using various methods."
  },
"paths": {
  "/api/search": {
    "post": {
      "summary": "Execute a Tanach search query",
      "description": "Search the Tanach using one of the supported methods.",
      "requestBody": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
               "$ref": "#/components/schemas/SearchRequest"
            },
            "examples": {
              "singleSearch": {
                "value": {
                  "method": "ww",
                  "option1": 2,
                  "option2": null,
                  "startNum": 1,
                  "endNum": 88,
                  "hitLimit": 9999,
                  "query": "בראשית"
                }
              }
            }
          }
        }
      },
      "responses": {
        "200": {
          "description": "Search results returned successfully",
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SearchResponse" }
            }
          }
        },
        "400": {
          "description": "Invalid input",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "error": { "type": "string" },
                  "details": { "type": "array", "items": { "type": "string" } }
                }
              }
            }
          }
        }
      }
    }
  }
},
  "components": {
    "schemas": {
      "SearchRequest": {
        "type": "object",
        "required": ["method", "startNum", "endNum", "hitLimit"],
        "properties": {
          "method": {
            "type": "string",
            "enum": ["ww", "ph", "be", "gm", "qd", "rst", "gp", "rsp"],
            "description": "Search method:\n- 'ww': Word search - Use for SINGLE Hebrew word or letter sequence (e.g., 'ברך')\n- 'ph': Phrase search - Use for MULTIPLE space-separated Hebrew words (e.g., 'בית רב'). Requires both option1 and option2.\n- 'be': Verse bookends - Find verses starting and ending with exactly 2 specific Hebrew letters\n- 'gm': Gematria - Search by numeric value of Hebrew letters\n- 'qd': Equidistant letter sequences (ELS/Bible codes) - Find letters at fixed intervals\n- 'rst': Word acronyms - Match specific letter positions in consecutive words\n- 'gp': Geometric patterns - Find verses with triangular or square word counts (no query needed)\n- 'rsp': Verse acronyms - Match first or last letters of consecutive verses"
          },
          "startNum": {
            "type": "integer",
            "minimum": 1,
            "maximum": 88,
            "description": "Starting parsha/book number (1-88). For Torah only, use 1-54. For 'qd' method, must be 1."
          },
          "endNum": {
            "type": "integer",
            "minimum": 1,
            "maximum": 88,
            "description": "Ending parsha/book number (1-88). For Torah only, use 1-54. For 'qd' method, must be 54."
          },
          "hitLimit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9999,
            "description": "Maximum number of results to return."
          }
        },
        "oneOf": [
          { "$ref": "#/components/schemas/WordSearch" },
          { "$ref": "#/components/schemas/PhraseSearch" },
          { "$ref": "#/components/schemas/VerseBookends" },
          { "$ref": "#/components/schemas/GematriaSearch" },
          { "$ref": "#/components/schemas/EquidistantSearch" },
          { "$ref": "#/components/schemas/WordAcronyms" },
          { "$ref": "#/components/schemas/GeometricSearch" },
          { "$ref": "#/components/schemas/VerseAcronyms" }
        ]
      },
      "WordSearch": {
          "type": "object",
          "properties": {
            "option1": {
              "type": "integer",
              "enum": [1, 2, 3, 4, 5],
              "description": "1: Contain letters in order, 2: Exact match (ONLY my letters), 3: Contain bound letters in order, 4: Start with letters in order, 5: End with letters in order."
            },
            "option2": {
              "oneOf": [
                {
                  "type": "string",
                  "pattern": "^[\\u0590-\\u05FF,\\s]*$",
                  "description": "Comma-separated Hebrew letters/words to exclude from results. Only applicable when option1 is 1 (CONTAINS), 3 (BOUND), or 5 (ENDS)."
                },
                {
                  "type": "null",
                  "description": "Must be null when option1 is 2 (EXACT/ONLY) or 4 (STARTS)."
                }
              ]
            },
            "query": {
              "type": "string",
              "pattern": "^[\\u0590-\\u05FF]+$",
              "description": "Single Hebrew word or letters to search for (no spaces)."
            }
          },
          "required": ["option1", "query"]
      },
      "PhraseSearch": {
        "type": "object",
        "properties": {
          "option1": {
            "type": "integer",
            "enum": [1, 2],
            "description": "1: Contain letters in order, 2: Exact match."
          },
          "option2": {
            "type": "integer",
            "enum": [1, 2],
            "description": "1: Adjacent words (words must be next to each other), 2: Non-adjacent words (words can be separated)."
          },
          "query": {
            "type": "string",
            "pattern": "^[\\u0590-\\u05FF\\s]+$",
            "description": "Multiple Hebrew words separated by spaces (e.g., 'בית רב')."
          }
        },
        "required": ["option1", "option2", "query"]
      },
      "VerseBookends": {
        "type": "object",
        "properties": {
          "option1": { "const": null },
          "option2": { "const": null },
          "query": {
            "type": "string",
            "pattern": "^[\\u0590-\\u05FF]{2}$",
            "description": "Exactly 2 Hebrew letters to match start/end of verses."
          }
        },
        "required": ["query"]
      },
      "GematriaSearch": {
        "type": "object",
        "properties": {
          "option1": {
            "type": "integer",
            "enum": [1, 2, 3, 4],
            "description": "1: Match verse total, 2: Match successive verses, 3: Match successive words, 4: Multiple of value."
          },
          "option2": { "const": null },
          "query": {
            "oneOf": [
              { "type": "string", "pattern": "^[\\u0590-\\u05FF]+$" },
              { "type": "integer" }
            ],
            "description": "Hebrew letters or numeric value for gematria."
          }
        },
        "required": ["option1", "query"]
      },
      "EquidistantSearch": {
        "type": "object",
        "properties": {
          "option1": {
            "type": "integer",
            "enum": [1, 2, 3, 4, 5, 6, 7],
            "description": "1-6: Fixed intervals; 7: Custom interval (requires option2)."
          },
          "option2": {
            "oneOf": [
              { "const": null },
              { "type": "integer", "minimum": 1, "description": "Custom skip interval (any positive integer). Required if option1 is 7." }
            ]
          },
          "startNum": { "const": 1 },
          "endNum": { "const": 54 },
          "query": {
            "type": "string",
            "pattern": "^[\\u0590-\\u05FF]+$",
            "description": "Hebrew letters to search for."
          }
        },
        "required": ["option1", "startNum", "endNum", "query"]
      },
      "WordAcronyms": {
        "type": "object",
        "properties": {
          "option1": {
            "type": "integer",
            "enum": [1, 2, 3, 4, 5, 6],
            "description": "1: 1st letter of words, 2: 2nd letter of words, 3: 3rd letter of words, 4: Last letter of words, 5: 2nd to last letter of words, 6: 3rd to last letter of words."
          },
          "option2": { "const": null },
          "query": {
            "type": "string",
            "pattern": "^[\\u0590-\\u05FF]+$",
            "description": "Hebrew letters to match."
          }
        },
        "required": ["option1", "query"]
      },
      "GeometricSearch": {
        "type": "object",
        "properties": {
          "option1": {
            "type": "integer",
            "enum": [1, 2, 3],
            "description": "1: Triangular, 2: Square, 3: Both."
          },
          "option2": { "const": null },
          "query": { "const": null, "description": "Not used for geometric searches." }
        },
        "required": ["option1"]
      },
      "VerseAcronyms": {
        "type": "object",
        "properties": {
          "option1": {
            "type": "integer",
            "enum": [1, 2],
            "description": "1: Start letters of verses, 2: Last letters of verses."
          },
          "option2": { "const": null },
          "query": {
            "type": "string",
            "pattern": "^[\\u0590-\\u05FF]+$",
            "description": "Hebrew letters to match."
          }
        },
        "required": ["option1", "query"]
      },
      "SearchResponse": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": { "type": "object" }
          },
          "count": { "type": "integer" },
          "query": { "type": "string" }
        }
      },
      "BookIndex": {
        "type": "object",
        "description": "Mapping of parsha/book numbers to their Hebrew names",
        "additionalProperties": { "type": "string" },
        "example": {
          "1": "בראשית", "2": "נח", "3": "לך לך", "4": "וירא", "5": "חיי שרה", "6": "תולדות", "7": "ויצא", "8": "וישלח",
          "9": "וישב", "10": "מקץ", "11": "ויגש", "12": "ויחי", "13": "שמות", "14": "וארא", "15": "בא", "16": "בשלח",
          "17": "יתרו", "18": "משפטים", "19": "תרומה", "20": "תצוה", "21": "כי תשא", "22": "ויקהל", "23": "פקודי",
          "24": "ויקרא", "25": "צו", "26": "שמיני", "27": "תזריע", "28": "מצורע", "29": "אחרי מות", "30": "קדושים",
          "31": "אמור", "32": "בהר", "33": "בחקתי", "34": "במדבר", "35": "נשא", "36": "בהעלותך", "37": "שלח", "38": "קרח",
          "39": "חקת", "40": "בלק", "41": "פנחס", "42": "מטות", "43": "מסעי", "44": "דברים", "45": "ואתחנן", "46": "עקב",
          "47": "ראה", "48": "פרשת שופטים", "49": "כי תצא", "50": "כי תבוא", "51": "נצבים", "52": "וילך", "53": "האזינו",
          "54": "וזאת הברכה", "55": "יהושע", "56": "ספר שופטים", "57": "שמואל א", "58": "שמואל ב", "59": "מלכים א",
          "60": "מלכים ב", "61": "תהילים", "62": "ישעיה", "63": "ירמיה", "64": "יחזקאל", "65": "הושע", "66": "יואל",
          "67": "עמוס", "68": "עובדיה", "69": "שיר השירים", "70": "אסתר", "71": "יונה", "72": "מיכה", "73": "נחום",
          "74": "חבקוק", "75": "צפניה", "76": "חגי", "77": "זכריה", "78": "מלאכי", "79": "קהלת", "80": "איכה",
          "81": "משלי", "82": "רות", "83": "איוב", "84": "דניאל", "85": "עזרא", "86": "נחמיה", "87": "דברי הימים א", "88": "דברי הימים ב"
        }
      }
    }
  }
}