{
 "openapi": "3.1.0",
 "info": {
  "title": "البيان — Bayan API",
  "version": "1.0.0",
  "description": "Read-only data of Bayan, an Arabic Islamic encyclopedia sourced from the Qur'an and authentic hadith: verses with tafsir, hadith with grade and chain, articles and answers. No key. Show «البيان» and the item's `link` with every text you use. Limits: 120 requests/minute and 5,000/day per IP; 503 with Retry-After when busy.",
  "contact": {
   "url": "https://bayan.alwa7i.com/"
  },
  "license": {
   "name": "Texts: OpenITI CC BY-NC-SA 4.0; Qur'an: Tanzil; articles © البيان with attribution",
   "url": "https://bayan.alwa7i.com/api"
  }
 },
 "servers": [
  {
   "url": "https://bayan.alwa7i.com"
  }
 ],
 "paths": {
  "/api/hadith/{book}/{seq}": {
   "get": {
    "operationId": "getHadith",
    "summary": "A hadith: its text, chain, the book's grade, narrators' names, takhrij, and Bayan's articles about it",
    "parameters": [
     {
      "name": "book",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "sabil-al-rashad",
        "sahih-al-bukhari",
        "sahih-muslim",
        "sunan-abi-dawud",
        "jami-al-tirmidhi",
        "sunan-al-nasai",
        "sunan-ibn-majah",
        "musnad-ahmad",
        "al-muwatta"
       ]
      }
     },
     {
      "name": "seq",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1
      },
      "description": "Place of the unit in the book (as in site links /hadith/{book}/{seq}); prefaces and chapter headings have no hadith number. To fetch by the hadith's cited number use /api/hadith/{book}?number="
     }
    ],
    "responses": {
     "200": {
      "description": "The hadith",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "book": {
           "type": "string"
          },
          "bookTitle": {
           "type": "string"
          },
          "number": {
           "type": [
            "integer",
            "null"
           ]
          },
          "seq": {
           "type": "integer"
          },
          "citation": {
           "type": "string"
          },
          "chapter": {
           "type": [
            "string",
            "null"
           ]
          },
          "chain": {
           "type": [
            "string",
            "null"
           ]
          },
          "text": {
           "type": "string"
          },
          "fullText": {
           "type": "string"
          },
          "grade": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "label": {
             "type": "string"
            },
            "basis": {
             "type": "string"
            }
           }
          },
          "takhrij": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "narrators": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "name": {
              "type": "string"
             },
             "link": {
              "type": "string"
             }
            }
           }
          },
          "link": {
           "type": "string",
           "format": "uri",
           "description": "The item's page on bayan.alwa7i.com — show it with the text."
          },
          "relatedArticles": {
           "type": "array",
           "description": "Bayan's own articles about this very item.",
           "items": {
            "type": "object",
            "properties": {
             "title": {
              "type": "string"
             },
             "kind": {
              "type": "string",
              "enum": [
               "article",
               "answer"
              ]
             },
             "link": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "source": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/api/quran/{surah}/{ayah}": {
   "get": {
    "operationId": "getVerse",
    "summary": "A verse of the Qur'an with passages of its tafsir (al-Sa'di, Ibn Kathir, al-Tabari, Ibn Ashur) and Bayan's articles about it",
    "parameters": [
     {
      "name": "surah",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 114
      }
     },
     {
      "name": "ayah",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 286
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The verse",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "surah": {
           "type": "integer"
          },
          "ayah": {
           "type": "integer"
          },
          "reference": {
           "type": "string"
          },
          "text": {
           "type": "string"
          },
          "tafsir": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "book": {
              "type": "string"
             },
             "citation": {
              "type": "string"
             },
             "text": {
              "type": "string"
             },
             "truncated": {
              "type": "boolean"
             },
             "link": {
              "type": "string"
             }
            }
           }
          },
          "link": {
           "type": "string",
           "format": "uri",
           "description": "The item's page on bayan.alwa7i.com — show it with the text."
          },
          "relatedArticles": {
           "type": "array",
           "description": "Bayan's own articles about this very item.",
           "items": {
            "type": "object",
            "properties": {
             "title": {
              "type": "string"
             },
             "kind": {
              "type": "string",
              "enum": [
               "article",
               "answer"
              ]
             },
             "link": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "No such verse"
     }
    }
   }
  },
  "/api/articles": {
   "get": {
    "operationId": "listArticles",
    "summary": "Bayan's latest published articles and answers, 20 a page",
    "parameters": [
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1
      }
     },
     {
      "name": "category",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "e.g. hadith, tawhid, fiqh (see /api)"
     }
    ],
    "responses": {
     "200": {
      "description": "A page of articles",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "page": {
           "type": "integer"
          },
          "next": {
           "type": [
            "string",
            "null"
           ]
          },
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "slug": {
              "type": "string"
             },
             "kind": {
              "type": "string"
             },
             "category": {
              "type": "string"
             },
             "title": {
              "type": "string"
             },
             "excerpt": {
              "type": [
               "string",
               "null"
              ]
             },
             "publishedAt": {
              "type": [
               "string",
               "null"
              ]
             },
             "link": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/articles/{slug}": {
   "get": {
    "operationId": "getArticle",
    "summary": "One article or answer in full (HTML and plain text)",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The article",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "title": {
           "type": "string"
          },
          "excerpt": {
           "type": [
            "string",
            "null"
           ]
          },
          "html": {
           "type": "string"
          },
          "text": {
           "type": "string"
          },
          "link": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  },
  "/api/narrator": {
   "get": {
    "operationId": "getNarrator",
    "summary": "A hadith narrator: the link to his page on Bayan (rank and the critics' words) and Bayan's articles that mention him",
    "parameters": [
     {
      "name": "name",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "minLength": 3
      }
     }
    ],
    "responses": {
     "200": {
      "description": "The narrator",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "name": {
           "type": "string"
          },
          "link": {
           "type": "string"
          },
          "relatedArticles": {
           "type": "array",
           "description": "Bayan's own articles about this very item.",
           "items": {
            "type": "object",
            "properties": {
             "title": {
              "type": "string"
             },
             "kind": {
              "type": "string",
              "enum": [
               "article",
               "answer"
              ]
             },
             "link": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/search": {
   "get": {
    "operationId": "searchBayan",
    "summary": "Search verses, hadiths (Sabil al-Rashad, Sahih al-Bukhari, Sahih Muslim) and Bayan's articles containing the given Arabic words",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "minLength": 2,
       "maxLength": 120
      },
      "description": "Arabic words, e.g. إنما الأعمال بالنيات"
     }
    ],
    "responses": {
     "200": {
      "description": "A few matches of each kind, each with its API url and its page link",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "query": {
           "type": "string"
          },
          "verses": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "reference": {
              "type": "string"
             },
             "text": {
              "type": "string"
             },
             "api": {
              "type": "string",
              "format": "uri"
             },
             "link": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "hadith": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "citation": {
              "type": "string"
             },
             "text": {
              "type": "string"
             },
             "api": {
              "type": "string",
              "format": "uri"
             },
             "link": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "articles": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "title": {
              "type": "string"
             },
             "kind": {
              "type": "string",
              "enum": [
               "article",
               "answer"
              ]
             },
             "api": {
              "type": "string",
              "format": "uri"
             },
             "link": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Missing or too-short query"
     }
    }
   }
  },
  "/api/hadith/{book}": {
   "get": {
    "operationId": "getHadithByNumber",
    "summary": "A hadith by its number in the book as it is cited (e.g. Sahih al-Bukhari 1)",
    "parameters": [
     {
      "name": "book",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "sabil-al-rashad",
        "sahih-al-bukhari",
        "sahih-muslim",
        "sunan-abi-dawud",
        "jami-al-tirmidhi",
        "sunan-al-nasai",
        "sunan-ibn-majah",
        "musnad-ahmad",
        "al-muwatta"
       ]
      }
     },
     {
      "name": "number",
      "in": "query",
      "required": true,
      "schema": {
       "type": "integer",
       "minimum": 1
      },
      "description": "The hadith's number in the book"
     }
    ],
    "responses": {
     "200": {
      "description": "The hadith",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "book": {
           "type": "string"
          },
          "bookTitle": {
           "type": "string"
          },
          "number": {
           "type": [
            "integer",
            "null"
           ]
          },
          "seq": {
           "type": "integer"
          },
          "citation": {
           "type": "string"
          },
          "chapter": {
           "type": [
            "string",
            "null"
           ]
          },
          "chain": {
           "type": [
            "string",
            "null"
           ]
          },
          "text": {
           "type": "string"
          },
          "fullText": {
           "type": "string"
          },
          "grade": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "label": {
             "type": "string"
            },
            "basis": {
             "type": "string"
            }
           }
          },
          "takhrij": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "narrators": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "name": {
              "type": "string"
             },
             "link": {
              "type": "string"
             }
            }
           }
          },
          "link": {
           "type": "string",
           "format": "uri",
           "description": "The item's page on bayan.alwa7i.com — show it with the text."
          },
          "relatedArticles": {
           "type": "array",
           "description": "Bayan's own articles about this very item.",
           "items": {
            "type": "object",
            "properties": {
             "title": {
              "type": "string"
             },
             "kind": {
              "type": "string",
              "enum": [
               "article",
               "answer"
              ]
             },
             "link": {
              "type": "string",
              "format": "uri"
             }
            }
           }
          },
          "source": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Not found"
     }
    }
   }
  }
 }
}