Al-Mizan | Quickstart

Read a verse.

Surah and ayah are the path. The text is Tanzil’s Hafs ‘an ‘Asim, and the response says so rather than leaving you to assume it.

Request

curl https://almizan.page/api/v1/verse/55/9

Response

{
  "id": "quran_verse:55_9",
  "surah": 55,
  "ayah": 9,
  "text_uthmani": "وَأَقِيمُوا۟ ٱلْوَزْنَ بِٱلْقِسْطِ",
  "juz": 29,
  "place": "Madinah",
  "attribution": "Tanzil Project (Hafs 'an 'Asim, Mushaf al-Madinah)"
}

Search hadith.

Results carry the collection’s own numbering and its edition, so a citation made from this response resolves in the printed text.

Request

curl "https://almizan.page/api/v1/hadith/search?q=intention&limit=1"

Response

{
  "count": 1,
  "hadiths": [
    {
      "id": "hadith:bukhari_81_6499",
      "collection": "bukhari",
      "book_number": 81,
      "hadith_number": "6499",
      "attribution": "Ṣaḥīḥ al-Bukhārī (Dār Ṭawq al-Najāh)"
    }
  ]
}

Walk the graph.

Any node id from a response can be expanded. You get the node, its neighbours, and the edge that connects them, each labelled with the tier it belongs to and whether that tier may ever change.

Request

curl "https://almizan.page/api/v1/graph/expand?id=quran_verse:55_9"

Response

{
  "nodes": [
    {
      "id": "quran_verse:55_9",
      "label": "55:9",
      "node_type": "quran_verse",
      "tier": "Tier 1",
      "tier_level": 1,
      "mutability": "CONSTANT"
    }
  ],
  "edges": [ { "label": "has_root", "source": "...", "target": "..." } ]
}

Every error has the same shape.

A failure is a response, not a surprise. The status is in the body as well as the header, and details names what was actually asked for.

404

{
  "error": {
    "code": "not_found",
    "message": "Ruling \"quran_verse:55_9\" not found",
    "details": { "ruling_id": "quran_verse:55_9" },
    "status": 404
  }
}

Where a token is required.

Reading is open. A token is needed only to act inside the Majlis: proposing a ruling, and signing or rejecting one. Get one from POST /auth/signin, send it as Authorization: Bearer <token>.

The signatory is never taken from the request body. It is resolved from the token against the scholar register, so a client cannot assert who signed.

POST /api/v1/authority/propose: Submit a ruling with its chain of evidence for review.
POST /api/v1/authority/sign: Confirm the chain behind a proposed ruling. Attributed in the record.
POST /api/v1/authority/reject: Record that the chain does not hold. Also attributed.

Limits.

20 requests per second, bursting to 100, keyed on the calling address. The limit exists to stop scrapers and runaway loops; a person driving the playground will not reach it.

Published uptime: not yet weighed

Run a query