{
  "openapi": "3.0.3",
  "info": {
    "title": "Halal or Not?",
    "version": "1.0.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."
  },
  "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"
                    ]
                  }
                }
              }
            }
          }
        },
        "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.",
        "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."
          }
        ],
        "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 against AAOIFI, Dow Jones Islamic, S&P Shariah and MSCI Islamic debt screens, via Mizan.",
        "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.",
        "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, with the rule on necessity.",
        "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/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"
          }
        }
      }
    }
  }
}