{
  "openapi": "3.0.3",
  "info": {
    "title": "Halal or Not?",
    "version": "1.1.0",
    "description": "Answers 'is it halal?' for food, cosmetics, medicines, stocks, funds, crypto, money products and everyday life, showing where the four Sunni schools and the main scholarly bodies agree and where they differ, with the reasoning and halal alternatives. Every answer has a 'verdict', a 'headline' and a 'say' line (one or two sentences to read aloud). Verdicts: halal, haram, doubtful, makruh (disliked), disputed (scholars differ; see views), depends (depends on how or what, see the reasoning), depends_on_school (the four schools differ; see by_school), depends_on_standard (stock and fund screening standards differ), not_in_rulebook, and for products no_ingredients or incomplete_data. Medicines lead with the ruling on necessity (ruling_if_needed).",
    "contact": {
      "name": "Halal or Not?",
      "email": "hello@askmizan.com",
      "url": "https://halalornot.pages.dev"
    }
  },
  "x-verdicts": [
    "halal",
    "haram",
    "doubtful",
    "makruh",
    "disputed",
    "depends",
    "depends_on_school",
    "depends_on_standard",
    "not_in_rulebook",
    "no_ingredients",
    "incomplete_data",
    "unknown"
  ],
  "servers": [
    {
      "url": "https://halalornot.pages.dev"
    }
  ],
  "paths": {
    "/api/v1/check": {
      "get": {
        "operationId": "checkIngredients",
        "summary": "Check an ingredients list",
        "description": "Pass the ingredients exactly as printed on the pack. Returns an overall verdict, a verdict for each school, and every flagged ingredient with the reason.",
        "parameters": [
          {
            "name": "ingredients",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Ingredients list as printed, comma separated."
          },
          {
            "name": "context",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "food",
                "cosmetic",
                "medicine"
              ],
              "default": "food"
            },
            "description": "'cosmetic' for products used on the skin, 'medicine' for medicines and supplements; these change how alcohol, carmine and necessity are treated."
          }
        ],
        "responses": {
          "200": {
            "description": "Verdict"
          }
        }
      },
      "post": {
        "operationId": "checkIngredientsPost",
        "summary": "Check an ingredients list (JSON body)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "ingredients"
                ],
                "properties": {
                  "ingredients": {
                    "type": "string"
                  },
                  "context": {
                    "type": "string",
                    "enum": [
                      "food",
                      "cosmetic",
                      "medicine"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verdict"
          }
        }
      }
    },
    "/api/v1/product/{barcode}": {
      "get": {
        "operationId": "checkProductByBarcode",
        "summary": "Check a product by barcode",
        "description": "Looks the barcode up in Open Food Facts, then Open Beauty Facts, and checks its ingredients.",
        "parameters": [
          {
            "name": "barcode",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "EAN-13, EAN-8 or UPC barcode digits."
          }
        ],
        "responses": {
          "200": {
            "description": "Verdict"
          },
          "404": {
            "description": "Barcode not found"
          }
        }
      }
    },
    "/api/v1/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Find products by name and check them",
        "description": "Searches Open Food Facts by name or brand (for example 'Haribo Starmix') and returns up to five matches, each with a verdict, plus a 'say' line for the best match. Where a brand states the source of an ingredient its label leaves unnamed (Haribo: pork gelatine in its standard UK range), that statement decides it and is quoted in brand_statement.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "default": "united-kingdom"
            },
            "description": "Open Food Facts country slug, for example united-kingdom, united-states, france. Use 'world' for no filter. Also picks the Amazon store for halal versions (amazon.co.uk for the UK and Ireland)."
          }
        ],
        "responses": {
          "200": {
            "description": "Matches with verdicts"
          }
        }
      }
    },
    "/api/v1/ingredient/{name}": {
      "get": {
        "operationId": "explainIngredient",
        "summary": "Explain one ingredient or E-number",
        "description": "For example 'E471', 'carmine', 'prawns', 'whey' or 'alcohol denat'. Returns the verdict for each school and the reasoning.",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "context",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "food",
                "cosmetic"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Explanation"
          }
        }
      }
    },
    "/api/v1/stock/{ticker}": {
      "get": {
        "operationId": "screenStock",
        "summary": "Is this stock halal?",
        "description": "Screens a US-listed stock via Mizan: first the business (each standard's excluded industries), then the AAOIFI, Dow Jones Islamic, S&P Shariah and MSCI Islamic debt screens. A company name also works (nvidia, philip morris). Links to halal alternatives in the same industry.",
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Screen result"
          },
          "404": {
            "description": "Not covered"
          }
        }
      }
    },
    "/api/v1/ask": {
      "get": {
        "operationId": "askIsItHalal",
        "summary": "Ask any 'is it halal' question",
        "description": "Covers money (savings, credit cards, mortgages, BNPL, insurance, pensions, trading), crypto, medicine, food and drink, and everyday life (music, dogs, tattoos, nail polish, smoking, games, photos, jobs). Returns the verdict, the main scholarly views and halal alternatives. Also recognises single ingredients and E-numbers.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The question in plain words, for example 'Is a credit card halal?'"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching topics with views"
          }
        }
      }
    },
    "/api/v1/fund/{ticker}": {
      "get": {
        "operationId": "checkFund",
        "summary": "Is this fund, ETF or pension fund halal?",
        "description": "Recognises Shariah funds by name or ticker. For other US-registered funds and ETFs, reads the latest SEC holdings report and screens every holding by industry and debt. UK-listed ETFs (VUSA, CSPX, VWRL, SWDA, EQQQ, ISF and others) and fund names (Vanguard S&P 500, FTSE 100 tracker, LifeStrategy) are answered through a US fund tracking the same index, or from what the index holds, with UK Shariah options.",
        "parameters": [
          {
            "name": "ticker",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Fund or ETF ticker (VOO, QQQ, SPUS) or a Shariah fund name."
          }
        ],
        "responses": {
          "200": {
            "description": "Fund screen"
          },
          "404": {
            "description": "Not a US-registered fund"
          }
        }
      }
    },
    "/api/v1/crypto/{coin}": {
      "get": {
        "operationId": "checkCrypto",
        "summary": "Is this cryptocurrency halal?",
        "description": "Classifies a coin by what it does (lending, gambling, meme, stablecoin, staking, general-purpose) and gives the scholarly views on crypto and on how it's used.",
        "parameters": [
          {
            "name": "coin",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Coin name or symbol, for example bitcoin, ETH, AAVE."
          }
        ],
        "responses": {
          "200": {
            "description": "Coin reading"
          }
        }
      }
    },
    "/api/v1/medicine": {
      "get": {
        "operationId": "checkMedicine",
        "summary": "Is this medicine halal?",
        "description": "Reads a medicine's active and inactive ingredients from its US label (openFDA) and flags gelatine, alcohol, pig-derived enzymes and heparin. The headline and say line lead with the ruling on necessity, so nobody stops a prescribed medicine; the ingredient reading follows (ingredient_headline, verdict).",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Brand or generic name."
          }
        ],
        "responses": {
          "200": {
            "description": "Verdict"
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/v1/prayer-times": {
      "get": {
        "operationId": "getPrayerTimes",
        "summary": "Today's prayer times for a place, with both Asr times and Ramadan suhoor and iftar",
        "parameters": [
          {
            "name": "city",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "Dearborn, Michigan"
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": false,
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "date",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "name": "method",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "isna",
                "mwl",
                "umm_al_qura",
                "egypt",
                "karachi",
                "moonsighting"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Prayer times"
          },
          "404": {
            "description": "Place not found"
          }
        }
      }
    },
    "/api/v1/topics": {
      "get": {
        "operationId": "listTopics",
        "summary": "Every question the rulebook covers",
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "money",
                "crypto",
                "medicine",
                "food",
                "life"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Topic list"
          }
        }
      }
    },
    "/api/v1/schools": {
      "get": {
        "operationId": "explainSchools",
        "summary": "How the four schools differ on food",
        "responses": {
          "200": {
            "description": "Explanation"
          }
        }
      }
    },
    "/api/v1/rules": {
      "get": {
        "operationId": "listRules",
        "summary": "The full rulebook",
        "responses": {
          "200": {
            "description": "Every rule with its verdict per school"
          }
        }
      }
    }
  }
}