User-related API environment

Production user-related API docs

These pages describe the Production user-related API stack.

Use production OAuth credentials, production API base URLs, and production app URLs when following this documentation.

Need to test before going live? Switch to the Pre-live docs using the environment switcher above.

Generate a Share Verse image

Generates a square image for one ayah or an ascending, same-Surah range of two to seven ayahs. The endpoint is available without authentication and may reject otherwise valid ranges when the selected content cannot fit within readable image bounds.

application/json

Request Body required

verseKey string required

Possible values: Value must match regular expression ^(\d+):(\d+)$

The ayah key to render, or the first ayah key of a range.

endVerseKey string

Possible values: Value must match regular expression ^(\d+):(\d+)$

The inclusive final ayah key. It must follow verseKey in the same Surah and produce a range of two to seven ayahs. Omit it for a single-ayah image.

locale string

Possible values: [en, ar, bn, fa, fr, id, it, nl, pt, ru, sq, th, tr, ur, zh, ms, es, sw, vi]

The Quran.com interface locale used for the Surah name, numerals, and direction. When omitted, the renderer uses its legacy default locale.

translations integer[] required

Possible values: >= 1

Translation resource IDs to render, in display order. Use an empty array for Arabic only.

Responses

• 200
• 400
• 401
• 403
• 404
• 422
• 429
• 500
• 502
• 503
• 504

---

Request has been handled successfully.

application/json

Schema

Example (from schema)

Example

---

Schema

success boolean
data object

url string required

The generated image URL.

{
  "success": true,
  "data": {
    "url": "https://images.quran.com/share/surah-al-kahf-18-ayahs-1-to-5-quran.png"
  }
}

{
  "success": true,
  "data": {
    "url": "https://images.quran.com/share/surah-al-kahf-18-ayahs-1-to-5-quran.png"
  }
}

The request is missing required parameters or is invalid.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The request is missing required headers or is invalid",
  "type": "invalid_request",
  "success": false
}

{
  "message": "The request is missing required headers or is invalid",
  "type": "invalid_request",
  "success": false
}

The request is unauthorized.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The request requires user authentication",
  "type": "unauthorized",
  "success": false
}

{
  "message": "The request requires user authentication",
  "type": "unauthorized",
  "success": false
}

Forbidden error. Can either be due to access token not being passed, having been expired or the caller trying to access a resource without enough permissions.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server understood the request, but refuses to authorize it",
  "type": "forbidden",
  "success": false
}

{
  "message": "The server understood the request, but refuses to authorize it",
  "type": "forbidden",
  "success": false
}

Not Found. The resource being accessed does not exist.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The requested resource could not be found",
  "type": "not_found",
  "success": false
}

{
  "message": "The requested resource could not be found",
  "type": "not_found",
  "success": false
}

The requested range is invalid, exceeds seven ayahs, or cannot fit in the readable image bounds.

application/json

Schema

Example (from schema)

rangeLimitExceeded

rangeTooLarge

---

Schema

success boolean required

Possible values: [false]

error object required
code string required
Possible values: [ValidationError, ShareVerseRangeLimitExceeded, ShareVerseRangeTooLarge]
message string required
details object

{
  "success": false,
  "error": {
    "code": "ValidationError",
    "message": "string",
    "details": {}
  }
}

The range contains more than seven ayahs

{
  "success": false,
  "error": {
    "code": "ShareVerseRangeLimitExceeded",
    "message": "Share Verse supports up to 7 ayahs"
  }
}

The selected content cannot fit in a readable image

{
  "success": false,
  "error": {
    "code": "ShareVerseRangeTooLarge",
    "message": "ShareVerseRangeTooLarge"
  }
}

Too many requests. Retry after the communicated interval.

Response Headers

• RateLimit-Policy string

  Rate-limit policy for the current request window.

• RateLimit-Limit integer

  Maximum number of requests allowed in the current window.

• RateLimit-Remaining integer

  Number of requests remaining in the current window.

• RateLimit-Reset integer

  Seconds until the current rate-limit window resets.

• Retry-After integer

  Seconds to wait before retrying the request.

application/json

Schema

Example (from schema)

Example

---

Schema

status integer required

Possible values: [429]

message string required

{
  "status": 429,
  "message": "string"
}

{
  "status": 429,
  "message": "Too many requests, please try again later"
}

Server Error. Something went wrong, try again later.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server encountered an internal error and was unable to complete your request",
  "type": "internal_server_error",
  "success": false
}

{
  "message": "The server encountered an internal error and was unable to complete your request",
  "type": "internal_server_error",
  "success": false
}

Invalid response from the upstream server

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
  "type": "bad_gateway",
  "success": false
}

{
  "message": "The server was acting as a gateway or proxy and received an invalid response from the upstream server",
  "type": "bad_gateway",
  "success": false
}

The server is currently unable to handle the request due to a temporary overload or scheduled maintenance

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
  "type": "service_unavailable",
  "success": false
}

{
  "message": "The server is currently unable to handle the request due to a temporary overload or scheduled maintenance",
  "type": "service_unavailable",
  "success": false
}

The server did not receive a timely response from the upstream server.

application/json

Schema

Example (from schema)

Example

---

Schema

message string
type string
success boolean

{
  "message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
  "type": "gateway_timeout",
  "success": false
}

{
  "message": "The server was acting as a gateway or proxy and did not receive a timely response from the upstream server",
  "type": "gateway_timeout",
  "success": false
}

Loading...