{
  "openapi": "3.1.0",
  "info": {
    "title": "QuranEnc.com API",
    "version": "1.0.0",
    "description": "Public, read-only API (plus a note-submission endpoint) for the translations of the meanings of the Noble Quran published on QuranEnc.com. No authentication is required. CORS is open (Access-Control-Allow-Origin: *). Human-readable docs: https://quranenc.com/en/home/api . Agent-oriented summary: https://quranenc.com/llms.txt",
    "contact": { "url": "https://quranenc.com" }
  },
  "servers": [{ "url": "https://quranenc.com/api/v1" }],
  "tags": [
    { "name": "Translations", "description": "Discover available translations and their versions" },
    { "name": "Ayat", "description": "Fetch translated ayat" },
    { "name": "Sura names", "description": "Localized sura names" },
    { "name": "Notes", "description": "Submit feedback on a translation" }
  ],
  "paths": {
    "/translations/list": {
      "get": {
        "tags": ["Translations"],
        "operationId": "listTranslations",
        "summary": "List all available translations",
        "parameters": [{ "$ref": "#/components/parameters/localization" }],
        "responses": {
          "200": {
            "description": "Available translations",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationList" } } }
          }
        }
      }
    },
    "/translations/list/{language}": {
      "get": {
        "tags": ["Translations"],
        "operationId": "listTranslationsByLanguage",
        "summary": "List available translations for one language",
        "parameters": [
          {
            "name": "language",
            "in": "path",
            "required": true,
            "description": "Language ISO code of the translations to return (see /translations/languages).",
            "schema": { "type": "string", "examples": ["es"] }
          },
          { "$ref": "#/components/parameters/localization" }
        ],
        "responses": {
          "200": {
            "description": "Available translations for the language (empty array if none)",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TranslationList" } } }
          }
        }
      }
    },
    "/translations/languages": {
      "get": {
        "tags": ["Translations"],
        "operationId": "listTranslationLanguages",
        "summary": "List the ISO codes of languages that have translations",
        "responses": {
          "200": {
            "description": "Language ISO codes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "languages": { "type": "array", "items": { "type": "string" } } }
                },
                "example": { "languages": ["en", "fr", "es"] }
              }
            }
          }
        }
      }
    },
    "/translations/isocodes": {
      "get": {
        "tags": ["Translations"],
        "operationId": "listIsoCodes",
        "summary": "Map between language names and ISO codes",
        "responses": {
          "200": {
            "description": "Both directions of the language/ISO-code mapping",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "languages_isocodes": { "type": "object", "additionalProperties": { "type": "string" }, "description": "language name -> ISO code" },
                    "isocodes_languages": { "type": "object", "additionalProperties": { "type": "string" }, "description": "ISO code -> language name" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/translations/locales": {
      "get": {
        "tags": ["Translations"],
        "operationId": "listLocales",
        "summary": "List locales accepted by the `localization` parameter",
        "responses": {
          "200": {
            "description": "Locale ISO codes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "locales": { "type": "array", "items": { "type": "string" } } }
                }
              }
            }
          }
        }
      }
    },
    "/translations/updates": {
      "get": {
        "tags": ["Translations"],
        "operationId": "getTranslationUpdate",
        "summary": "Get the current version of one translation",
        "parameters": [
          { "name": "key", "in": "query", "required": true, "description": "Translation key", "schema": { "type": "string", "examples": ["english_saheeh"] } }
        ],
        "responses": {
          "200": {
            "description": "Version info",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "key": { "type": "string" },
                    "direction": { "type": "string", "enum": ["ltr", "rtl"] },
                    "version": { "type": "string" },
                    "last_update": { "type": "integer", "description": "Unix timestamp" },
                    "database_url": { "type": "string", "format": "uri" },
                    "database_uncompressed_url": { "type": "string", "format": "uri" }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/translations/versions/{from}": {
      "get": {
        "tags": ["Translations"],
        "operationId": "listTranslationVersions",
        "summary": "List translation versions, optionally only those updated since a timestamp",
        "parameters": [
          { "name": "from", "in": "path", "required": true, "description": "Unix timestamp; use 0 to return all.", "schema": { "type": "integer", "examples": [0] } }
        ],
        "responses": {
          "200": {
            "description": "Versions (a bare JSON array)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "key": { "type": "string" },
                      "version": { "type": "string" },
                      "last_update": { "type": "integer", "description": "Unix timestamp" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/translation/sura/{translation_key}/{sura_number}": {
      "get": {
        "tags": ["Ayat"],
        "operationId": "getSuraTranslation",
        "summary": "Get every aya of a sura in a translation",
        "parameters": [
          { "$ref": "#/components/parameters/translation_key" },
          { "$ref": "#/components/parameters/sura_number" }
        ],
        "responses": {
          "200": {
            "description": "Ayat of the sura",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Aya" } } }
                }
              }
            }
          },
          "404": { "description": "Unknown translation key or invalid sura number (empty body)" }
        }
      }
    },
    "/translation/aya/{translation_key}/{sura_number}/{aya_number}": {
      "get": {
        "tags": ["Ayat"],
        "operationId": "getAyaTranslation",
        "summary": "Get a single aya in a translation",
        "parameters": [
          { "$ref": "#/components/parameters/translation_key" },
          { "$ref": "#/components/parameters/sura_number" },
          { "name": "aya_number", "in": "path", "required": true, "description": "Aya number within the sura (starts at 1)", "schema": { "type": "integer", "minimum": 1, "examples": [1] } },
          { "name": "without_footnotes_symbols", "in": "query", "required": false, "description": "If set to 1, footnote markers like [1] and * are stripped from `translation`.", "schema": { "type": "integer", "enum": [1] } }
        ],
        "responses": {
          "200": {
            "description": "The aya",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/Aya" } } }
              }
            }
          },
          "404": { "description": "Unknown translation key, or invalid sura/aya number (empty body)" }
        }
      }
    },
    "/translations/sowar_locales": {
      "get": {
        "tags": ["Sura names"],
        "operationId": "listSuraNameLocales",
        "summary": "List ISO codes that have localized sura names",
        "responses": {
          "200": {
            "description": "Locale ISO codes",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "locales": { "type": "array", "items": { "type": "string" } } } },
                "example": { "locales": ["ar", "en", "fr"] }
              }
            }
          }
        }
      }
    },
    "/translations/sowar_names": {
      "get": {
        "tags": ["Sura names"],
        "operationId": "getSuraNames",
        "summary": "Get the names of all 114 suras in a language",
        "parameters": [
          { "name": "iso_code", "in": "query", "required": false, "description": "One of the codes from /translations/sowar_locales. Defaults to en.", "schema": { "type": "string", "default": "en" } }
        ],
        "responses": {
          "200": {
            "description": "Object keyed by sura number (\"1\" to \"114\")",
            "content": {
              "application/json": {
                "schema": { "type": "object", "additionalProperties": { "type": "string" } },
                "example": { "1": "Al-Fātihah", "2": "Al-Baqarah", "114": "An-Nās" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/translations/note": {
      "post": {
        "tags": ["Notes"],
        "operationId": "submitNote",
        "summary": "Submit a note or correction for one aya of a translation",
        "description": "Sends feedback to the translation's reviewers. Only call this when a person has explicitly asked to submit feedback.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": { "schema": { "$ref": "#/components/schemas/NoteRequest" } },
            "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/NoteRequest" } },
            "multipart/form-data": { "schema": { "$ref": "#/components/schemas/NoteRequest" } }
          }
        },
        "responses": {
          "201": {
            "description": "Saved",
            "content": { "application/json": { "example": { "status": 1 } } }
          },
          "400": {
            "description": "Missing required parameters",
            "content": { "application/json": { "example": { "status": 0, "error": "Missing required parameters" } } }
          },
          "500": {
            "description": "Failed to save",
            "content": { "application/json": { "example": { "status": 0, "error": "Failed to save note" } } }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "localization": {
        "name": "localization",
        "in": "query",
        "required": false,
        "description": "Locale for `title` and `description` (see /translations/locales). Defaults to en.",
        "schema": { "type": "string", "default": "en" }
      },
      "translation_key": {
        "name": "translation_key",
        "in": "path",
        "required": true,
        "description": "Translation key, the `key` field from /translations/list.",
        "schema": { "type": "string", "examples": ["english_saheeh"] }
      },
      "sura_number": {
        "name": "sura_number",
        "in": "path",
        "required": true,
        "description": "Sura number",
        "schema": { "type": "integer", "minimum": 1, "maximum": 114, "examples": [1] }
      }
    },
    "responses": {
      "Error": {
        "description": "Invalid parameter",
        "content": {
          "application/json": {
            "schema": { "type": "object", "properties": { "error": { "type": "string" } } }
          }
        }
      }
    },
    "schemas": {
      "TranslationList": {
        "type": "object",
        "properties": {
          "translations": { "type": "array", "items": { "$ref": "#/components/schemas/Translation" } }
        }
      },
      "Translation": {
        "type": "object",
        "properties": {
          "key": { "type": "string", "description": "Translation key used by the other endpoints", "examples": ["english_saheeh"] },
          "direction": { "type": "string", "enum": ["ltr", "rtl"] },
          "language_iso_code": { "type": "string" },
          "version": { "type": "string" },
          "last_update": { "type": "integer", "description": "Unix timestamp" },
          "title": { "type": "string", "description": "Localized title" },
          "description": { "type": "string", "description": "Localized description" },
          "file": { "type": "string" },
          "database_url": { "type": "string", "format": "uri", "description": "Zipped SQLite database of the full translation" },
          "database_uncompressed_url": { "type": "string", "format": "uri" },
          "pdf_url": { "type": ["string", "null"], "format": "uri" },
          "pdf_size": { "type": ["integer", "null"] },
          "pdf_cover": { "type": ["string", "null"], "format": "uri" },
          "pdf_pure_url": { "type": ["string", "null"], "format": "uri" },
          "pdf_pure_size": { "type": ["integer", "null"] },
          "pdf_pure_cover": { "type": ["string", "null"], "format": "uri" },
          "pdf_mobile_url": { "type": ["string", "null"], "format": "uri" },
          "pdf_mobile_size": { "type": ["integer", "null"] },
          "pdf_mobile_cover": { "type": ["string", "null"], "format": "uri" },
          "epub_url": { "type": ["string", "null"], "format": "uri" },
          "epub_size": { "type": ["integer", "null"] }
        }
      },
      "Aya": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "sura": { "type": "string", "description": "Sura number (returned as a string)" },
          "aya": { "type": "string", "description": "Aya number (returned as a string)" },
          "arabic_text": { "type": "string", "description": "Uthmanic Hafs Arabic text; displays correctly with the Hafs v20 font (https://quranenc.com/downloads/assets/Hafs_20.zip)" },
          "translation": { "type": "string", "description": "Translated text; may contain footnote markers like [1]" },
          "footnotes": { "type": ["string", "null"], "description": "Footnotes for the aya" }
        }
      },
      "NoteRequest": {
        "type": "object",
        "required": ["translation_key", "sura", "aya", "note"],
        "properties": {
          "translation_key": { "type": "string" },
          "sura": { "type": "integer", "minimum": 1, "maximum": 114 },
          "aya": { "type": "integer", "minimum": 1 },
          "note": { "type": "string" },
          "version": { "type": "string", "description": "Translation version the note refers to" },
          "suggested_translation": { "type": "string" },
          "name": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "source": { "type": "string", "description": "App name or domain name" }
        }
      }
    }
  }
}