Reference Licence and attribution Endpoints Response schema Limits and errors Changelog

Licence and attribution

OpenDua’s independently authored English, transliteration, editorial metadata and dataset structure are licensed under CC BY 4.0. OpenDua makes no ownership claim over the underlying Quranic, hadith or supplication text. The recitation was recorded for OpenDua under a separate written agreement and is not offered under the dataset licence. Credit Hisn al-Muslim as the collection and paste the attribution below when reusing OpenDua material.

attribution.txt 
OpenDua dataset v0.0.4 (https://opendua.org), by Ihsan Labs at the Human Development Fund. Based on Hisn al-Muslim by Sa'id ibn Ali ibn Wahf al-Qahtani. OpenDua editorial text and dataset structure are licensed CC BY 4.0. Recitation by Muhammad Jumah for OpenDua. OpenDua makes no ownership claim over the underlying religious texts.

Endpoints

base https://api.opendua.org Open interactive API docs ↗
GET /v2 Current API and data release information
GET /v2/collections All dua collections
GET /v2/collections/{collectionId} One collection
GET /v2/collections/{collectionId}/chapters Chapters in a collection
GET /v2/collections/{collectionId}/chapters/{chapterId} One chapter
GET /v2/collections/{collectionId}/chapters/{chapterId}/entries Entry summaries in a chapter
GET /v2/collections/{collectionId}/entries Entry summaries in a collection
GET /v2/entries/{entryId} One complete contextual entry
GET /v2/duas/{duaId} One canonical dua
GET /v2/reciters All reciters
GET /v2/reciters/{reciterId} One reciter
GET /v2/reference-works Structured reference works
GET /v2/reference-works/{workId} One reference work
GET /v2/tags All topical tags
GET /v2/tags/{tagId}/entries Paginated entries carrying a tag
GET /v2/search?q= Paginated Arabic, transliteration, and English search
Example request
curl
curl https://api.opendua.org/v2/entries/entry-000001
Example response
200 OK · application/json
{
  "id": "entry-000001",
  "slug": "when-you-wake-up-1",
  "title": "Supplications for when you wake up (1 of 4)",
  "type": "invocation",
  "collectionId": "hisn-al-muslim",
  "chapterId": "chapter-000001",
  "sourceReference": "1",
  "tags": [
    "sleep-and-waking"
  ],
  "references": [],
  "variations": [
    {
      "id": "standard",
      "steps": [
        {
          "type": "recitation",
          "items": [
            {
              "dua": {
                "id": "dua-000001",
                "arabic": "الْحَمْدُ للَّهِ الَّذِي أَحْيَانَا بَعْدَ مَا أَمَاتَنَا، وَإِلَيْهِ النُّشُورُ",
                "transliteration": "Al-ḥamdu li-llāhi alladhī aḥyānā baʿda mā amātanā, wa ilayhi an-nushūr",
                "translation": "All praise is for Allah who gave us life after having taken it from us and unto Him is the resurrection.",
                "references": []
              }
            }
          ],
          "recordings": [
            {
              "id": "recording-000001",
              "reciterId": "reciter-0001",
              "url": "https://audio.opendua.org/hisn/v0.0.2/OD-001.mp3",
              "durationSeconds": 16
            }
          ]
        }
      ]
    }
  ]
}

Response schema

FieldTypeNotes
id string Permanent neutral identifier, such as entry-000003. Never reused.
slug string Readable website slug. Public relationships use IDs.
title string Human-readable entry title.
type string invocation, instruction, or narration.
collectionId string Permanent ID of the collection containing this entry.
chapterId string (optional) Permanent chapter ID. Omitted when a collection has no chapters.
sourceReference string (optional) Human-readable location in the source, such as the Hisn al-Muslim entry number.
tags string[] Topical tag IDs only.
references object[] Structured citations supporting the entry context. Empty when none are published.
variations object[] Invocation alternatives and their ordered steps. Instruction and narration entries use steps instead.

Limits and errors

60 requests a minute Per IP, unauthenticated, across all read endpoints. Exceed it and you get a 429 with a Retry-After header. Need more? Bundle the dataset instead.
Errors are JSON 
404 { "error": "not_found",
      "slug": "ayat-al-kurse" }
Same envelope for 400 and 429. No HTML error pages.
Caching Responses carry an ETag and a long max-age. Pin a version and the payload never changes under you.