Skip to main content

User-related API environment

Pre-live user-related API docs

These pages describe the Pre-live user-related API stack.

Use pre-live OAuth credentials, pre-live API base URLs, and pre-live app URLs when following this documentation. Keep your OAuth flow, API requests, callback URLs, and manual testing within the pre-live environment.

Add/update activity day​

Create or update the user's daily activity record for one date and one activity type. Activity Days power streaks, goals, and calendar-style progress.

This endpoint is for crediting what the user read, not for saving the latest resume location. Use POST /v1/reading-sessions separately to store the latest visible Surah/Ayah for "Continue reading" and "Recently read" UX.

For type=QURAN, send:

  • type: use QURAN when the activity is Quran reading progress.
  • seconds: active reading time, in seconds, for this sync batch. Quran.com increments this while the reader tab is focused and flushes it every few seconds.
  • ranges: inclusive verse ranges read in this sync batch, formatted as chapter:verse-chapter:verse. Quran.com queues visible verse keys and merges nearby keys into ranges before sending.
  • mushafId: the Mushaf layout/font the user is reading with. This lets the backend calculate page-based progress consistently with the client.
  • date: optional activity date in YYYY-MM-DD. If omitted, the server uses today's date in the x-timezone timezone. If passed, it must be today or a past date.

A robust client implementation can follow this pattern, adapted from Quran.com's reader flow.

  1. When a verse becomes visible, queue its verse key and debounce a POST /v1/reading-sessions call for the latest location.
  2. Track active reading seconds while the browser tab is focused.
  3. Every few seconds, merge the queued verse keys into ranges and call POST /v1/activity-days with type, seconds, ranges, and mushafId.
  4. Keep in-flight queue entries recoverable until the activity-days request succeeds. If it fails, requeue them for retry and keep the buffered seconds.
Header Parameters
    x-timezone string

    The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.

Request Body
    oneOf
    seconds integer required

    Possible values: >= 1

    Active reading time, in seconds, to credit for this sync batch of ranges.

    ranges string[] required

    Possible values: Value must match regular expression ^(\d+:\d+-\d+:\d+(?:,\d+:\d+-\d+:\d+)*)$

    Inclusive Ayah ranges read in this sync batch, formatted as chapter:verse-chapter:verse.

    mushafId integer required

    Possible values: [1, 2, 3, 4, 5, 6, 7, 11, 19]

    The id of the Mushaf being used.

    1 = QCFV2

    2 = QCFV1

    3 = Indopak

    4 = UthmaniHafs

    5 = KFGQPCHAFS

    6 = Indopak15Lines

    7 = Indopak16Lines

    11 = Tajweeed

    19 = QCFTajweedV4

    date string

    Possible values: Value must match regular expression ^\d{4}-\d{2}-\d{2}$

    Optional activity date for the activity day. If omitted, the server uses today in the x-timezone timezone. If passed, it must be today or a past date.

    type string required

    Possible values: [QURAN, LESSON, QURAN_READING_PROGRAM]

    The activity category. Use QURAN for Quran reading progress; other values are for lessons and Quran reading programs.

Responses

Request has been handled successfully.

Schema
    success boolean
    data object
Loading...