Skip to main content

Sync public content resources​

Use this endpoint when your app keeps a local copy of public Quran.Foundation content and needs to know what changed without downloading everything again.

A resource is one public content item, such as translations:19, tafsirs:151, recitations:10, or articles:123. A full copy, called a snapshot in the API, is the complete current row list for one resource.

When next_page_url or mutation snapshot_url is present and non-null, we return a relative /api/v4/... API path, such as /api/v4/resources/sync?cursor=... or /api/v4/resources/snapshots/translations/19. You should prefix that path with the Content service e.g. https://apis.quran.foundation/content.

Recommended client flow:

  1. First sync: call with bootstrap=true and a resources filter.
  2. Follow next_page_url until has_more is false.
  3. Fetch every non-null snapshot_url and replace the local rows for that resource.
  4. Store next_sync_token from the final page only.
  5. Later syncs: call with sync_token and the same canonical resources filter to receive only newer changes.

Change handling:

  • RESOURCE_CREATE and RESOURCE_INVALIDATE: fetch snapshot_url, then replace all local rows for that resource.
  • RESOURCE_DELETE: remove or hide the full local resource.
  • ROW_CREATE and ROW_UPDATE: upsert one local row using record_type and record_key.
  • ROW_DELETE: delete one local row using record_type and record_key.
  • RESOURCE_UPDATE: freshness marker only. Keep existing local rows.

Bootstrap example:

curl "https://apis.quran.foundation/content/api/v4/resources/sync?bootstrap=true&resources=translations:19;tafsirs:151&per_page=100" \
  -H "x-auth-token: $ACCESS_TOKEN" \
  -H "x-client-id: $CLIENT_ID"

Incremental example:

curl "https://apis.quran.foundation/content/api/v4/resources/sync?sync_token=$SYNC_TOKEN&resources=translations:19;tafsirs:151&per_page=100" \
  -H "x-auth-token: $ACCESS_TOKEN" \
  -H "x-client-id: $CLIENT_ID"

Sync responses are not cacheable and return Cache-Control: no-store.

Query Parameters
    resources string

    Which public content your app wants to track. Required unless cursor is supplied. Format: group:* or group:id,id; groups are separated by semicolons. Store sync tokens per canonical/normalized resource filter.

    Example: articles:*;recitations:10;tafsirs:151;translations:1,6
    bootstrap boolean

    Set to true for first sync. The response pages current public resources as RESOURCE_CREATE changes with snapshot_url values.

    sync_token string

    Opaque checkpoint returned by the final bootstrap or incremental page. Send it on the next sync with the same canonical resources filter.

    cursor string

    Opaque pagination cursor from next_page_url. Use the returned relative path and do not construct cursors manually. Prefix the returned /api/v4/... path with the Content API gateway root: https://apis.quran.foundation/content.

    per_page integer

    Possible values: >= 1 and <= 100

    Default value: 50

    Maximum changes or bootstrap resources per page. Defaults to 50 and cannot exceed 100.

Responses

Successful sync response

Response Headers
  • Cache-Control string

    Always no-store for sync responses.

Schema
    sync object required
    sync_until_sequence int64 required

    Upper sequence bound for this sync page set.

    has_more boolean required

    True when the client must call next_page_url for another page before storing a sync token.

    next_page_url string nullable required

    Next page path when has_more is true. When present, we return a relative /api/v4/... path, such as /api/v4/resources/sync?cursor=...; prefix it with https://apis.quran.foundation/content.

    next_sync_token string nullable required

    Checkpoint to store after the final page has been fully applied. Null on intermediate pages.

    mutations object[] required
  • Array [
    • sequence int64 required

    Monotonic server sequence for this content change.

    type object

    Type of content change the client should apply.

    resource_group ContentSyncResourceGroup required

    Possible values: [articles, recitations, tafsirs, translations]

    Public content group supported by Content Sync.

    resource_id int64 required

    Resource ID within the group, such as translation resource 19.

    resource_content_id int64 nullable required

    Underlying resource content ID when the resource is backed by resource_contents. It is null for article resources.

    record_type object nullable

    Row type inside the resource. Present for row-level changes. Current values include translation, tafsir, audio_file, chapter_audio_file, and article_localization.

    record_key string nullable

    Client row key within the resource. Use resource_group + resource_id + record_type + record_key as the stable local row identity.

    source_record_id int64 nullable

    Present for row mutations when a source record ID is available.

    changed_at date-time required

    Server timestamp for when this content change was recorded.

    data object nullable

    Full row payload for ROW_CREATE and ROW_UPDATE. Null for deletes and resource-level changes.

    property name* any nullable

    Full row payload for ROW_CREATE and ROW_UPDATE. Null for deletes and resource-level changes.

    snapshot_url string nullable

    Present for RESOURCE_CREATE and RESOURCE_INVALIDATE. Fetch this full copy and replace local rows for the resource. When present, we return a relative /api/v4/... path; prefix it with https://apis.quran.foundation/content. RESOURCE_UPDATE does not include a snapshot URL.

    unavailable_reason string nullable

    Present for RESOURCE_DELETE when a public resource became unavailable.

  • ]
Loading...