{
  "openapi": "3.1.0",
  "info": {
    "title": "quranbench public API",
    "version": "0.8.0",
    "description": "Open, keyless, read-only access to the quranbench corpus. Every response carries the corpus version and the computation parameters that produced it. No key required; generous published rate limits.",
    "license": {
      "name": "See /data for per-artifact licences",
      "url": "https://quranbench.com/data"
    }
  },
  "servers": [
    {
      "url": "https://quranbench.com"
    }
  ],
  "paths": {
    "/api/v1": {
      "get": {
        "summary": "API index",
        "description": "Description of the API and its read endpoints.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "openapi": {
                      "type": "string"
                    },
                    "surah_count": {
                      "type": "integer"
                    },
                    "endpoints": {
                      "type": "object"
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "name",
                    "version",
                    "description",
                    "openapi",
                    "surah_count",
                    "endpoints",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/versions": {
      "get": {
        "summary": "List corpus versions",
        "description": "Every published corpus version resolvable through the API.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "current": {
                      "type": "string"
                    },
                    "versions": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "current",
                    "versions",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/manifest": {
      "get": {
        "summary": "Corpus manifest",
        "description": "The immutable build manifest for a corpus version: counts, sources, licences, numbering, normalisation rules and per-artifact checksums.",
        "parameters": [
          {
            "name": "version",
            "in": "query",
            "required": false,
            "description": "Corpus version, e.g. 0.7.0. Defaults to the current version.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "manifest": {
                      "type": "object"
                    },
                    "resolved_version": {
                      "type": "string"
                    },
                    "is_current": {
                      "type": "boolean"
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "manifest",
                    "resolved_version",
                    "is_current",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/surah/{number}": {
      "get": {
        "summary": "Surah with verses",
        "description": "Surah metadata and its verse list under the active numbering scheme.",
        "parameters": [
          {
            "name": "number",
            "in": "path",
            "required": true,
            "description": "Surah number, 1–114.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 114
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "surah": {
                      "type": "object"
                    },
                    "verses": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "surah",
                    "verses",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/verse/{surah}/{ordinal}": {
      "get": {
        "summary": "Verse or verse range",
        "description": "One verse or an inclusive range (e.g. 2/255 or 2/1-5) with its tokens and verse-level translations.",
        "parameters": [
          {
            "name": "surah",
            "in": "path",
            "required": true,
            "description": "Surah number, 1–114.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 114
            }
          },
          {
            "name": "ordinal",
            "in": "path",
            "required": true,
            "description": "Verse ordinal or inclusive range, e.g. 255 or 1-5.",
            "schema": {
              "type": "string",
              "pattern": "^\\d+(-\\d+)?$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reference": {
                      "type": "string"
                    },
                    "verses": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "reference",
                    "verses",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/token/{id}": {
      "get": {
        "summary": "Token with morphology",
        "description": "One addressable token, its text forms and full morphological annotation.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Opaque token identifier, e.g. quran:tanzil-uthmani:2:43:4.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "object"
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "token",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/root/{slug}": {
      "get": {
        "summary": "Root and occurrences",
        "description": "A triliteral root, its distribution, and one page of its occurrences.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Root transliteration slug, e.g. z-k-w.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Occurrence page (1-based).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "root": {
                      "type": "string"
                    },
                    "slug": {
                      "type": "string"
                    },
                    "transliteration": {
                      "type": "string"
                    },
                    "occurrences": {
                      "type": "integer"
                    },
                    "distinct_forms": {
                      "type": "integer"
                    },
                    "verse_count": {
                      "type": "integer"
                    },
                    "lemmas": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "surah_distribution": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "forms": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "url": {
                      "type": "string"
                    },
                    "api_url": {
                      "type": "string"
                    },
                    "occurrence_page": {
                      "type": "object"
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "root",
                    "slug",
                    "transliteration",
                    "occurrences",
                    "distinct_forms",
                    "verse_count",
                    "lemmas",
                    "surah_distribution",
                    "forms",
                    "url",
                    "api_url",
                    "occurrence_page",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "summary": "Search the corpus",
        "description": "Run a query in the corpus query language and page over matched tokens. The response carries the parsed query tree, corpus version and computation parameters.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "Query string, e.g. \"root:z-k-w\" or a reference like 2:43.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Result page (1-based).",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Results per page (1–500, default 50).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          },
          {
            "name": "basmala",
            "in": "query",
            "required": false,
            "description": "Include separated basmala tokens (0 or 1).",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "query_tree": {
                      "type": "object"
                    },
                    "total_matches": {
                      "type": "integer"
                    },
                    "distinct_verses": {
                      "type": "integer"
                    },
                    "page": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    },
                    "page_count": {
                      "type": "integer"
                    },
                    "matches": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "query",
                    "query_tree",
                    "total_matches",
                    "distinct_verses",
                    "page",
                    "per_page",
                    "page_count",
                    "matches",
                    "corpus_version",
                    "params",
                    "params_serialised",
                    "text_edition",
                    "numbering_scheme"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/resolve": {
      "get": {
        "summary": "Resolve a reference",
        "description": "Resolve a verse reference (s:v or s:v-w) to its verses under the active scheme.",
        "parameters": [
          {
            "name": "ref",
            "in": "query",
            "required": true,
            "description": "Verse reference, e.g. 2:43 or 2:43-45.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success. Carries corpus_version and params.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reference": {
                      "type": "string"
                    },
                    "verses": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "corpus_version": {
                      "type": "string"
                    },
                    "text_edition": {
                      "type": "string"
                    },
                    "numbering_scheme": {
                      "type": "string"
                    },
                    "params": {
                      "type": "object"
                    },
                    "params_serialised": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "reference",
                    "verses",
                    "corpus_version",
                    "text_edition",
                    "numbering_scheme",
                    "params",
                    "params_serialised"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}