Posts

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.

• Use prelive.quran.com for auth-related testing.
• Use prelive.quranreflect.org for Quran Reflect paths where applicable.
• Do not mix production sessions or production user data with pre-live testing.

Create, read, update, moderate, and interact with Quran Reflect posts.

📄️ Get posts feed

Retrieve a paginated feed of client-visible Quran Reflect posts, including reflections and lessons. Re-reflections are excluded from client post-type filters. Supports filtering by authors, tags, Quran references, groups, pages, and configured client-visible post type IDs. For example, use `tab=qdc&languages=2&filter[postTypeIds]=1` to retrieve English QDC reflections. Response items include engagement metadata such as `likesCount`, `commentsCount`, and `recentComment` when available. Use the dedicated comment endpoints to retrieve comment objects and totals. For ayah-by-ayah reads, use `filter[references][0][chapterId]`, `filter[references][0][from]`, and `filter[references][0][to]`.

📄️ Get related posts

Retrieve posts related to a given post by matching its Quran references with OR logic. Results are filtered by language preferences and ordered by popularity, excluding the source post.

📄️ Get post re-reflections

Retrieve paginated re-reflections of a source post for the post detail Re-Reflections tab. Returned posts are populated with author, references, tags, rooms, mentions, and engagement metadata, and exclude re-reflections authored by banned users or hidden/private-note moderation states.

📄️ Get current user posts

Retrieve posts created by the currently authenticated user. Supports filtering by tab (MY_REFLECTIONS, SAVED, DRAFTS), sorting options, and post type filtering.

📄️ Get posts count within range

Count how many posts the current user has written for verses within a specified Quran verse range. Useful for reading goals and progress tracking.

📄️ Get post liked state

Returns whether the authenticated user currently likes the post. This lightweight endpoint avoids loading the full post payload for simple like-state checks.

📄️ Get post by ID

Retrieve a specific post by its unique numeric ID. Returns the full post with author details, tags, references, room information, and engagement metrics. Admins can view additional moderation details.

📄️ Delete post

Soft-delete a post by marking it as removed. Only the post author or admins can delete posts. Related engagement counts (likes, comments, saves) update asynchronously via background jobs, so metrics may briefly lag.

📄️ Edit post

Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.

📄️ Track post view

Record that a post has been viewed by the current user (if authenticated). Used for analytics and engagement tracking. Does not require authentication but will track user-specific views when logged in.

📄️ Track post read

Record that a post has been read after the 100% reading-time threshold. Logged-in users are counted once per day. Guests are counted per accepted request.

📄️ Create post

Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.

📄️ Report post abuse

Report a post for moderation review. Provide a reason for the report to help moderators evaluate the content. Multiple reports on the same post may trigger automatic review.

📄️ Get user posts

Retrieve public posts created by a specific user. If viewing own posts while authenticated, returns all posts including drafts. Supports sorting and filtering by post type.

📄️ Toggle post like

Toggle like status for a post. If already liked, removes the like. If not liked, adds a like. Updates the post like count and triggers notifications.

📄️ Set or toggle a post reaction

The /v1/posts/{id}/reactions route requires an OAuth user access token in x-auth-token; client-credentials tokens are not accepted. The unversioned /posts/{id}/reactions alias instead requires the existing native session cookie. Both require a post visible to the authenticated user. Adds a reaction when none exists, changes a different reaction without changing the total, or removes the same reaction when selected again. This is a toggle, not an idempotent setter: do not automatically retry a mutation with an unknown outcome. Legacy likes are reaction1. Newly applied reactions use the existing like notification flow; changes and removals do not create another notification. Returns the service-native payload directly, with null values included for absent reactions. Gateway exposure and scope enforcement are managed separately.

📄️ Toggle post save

Toggle save/bookmark status for a post. Saved posts appear in the SAVED tab of the user profile for easy access later.

📄️ Get post comments

Retrieve paginated top-level comments for a post. Use the replies endpoint to get nested replies for specific comments.

📄️ Get all post comments

Retrieve all comments for a post in a single request without pagination. Useful for displaying full comment threads or export scenarios.

📄️ Export posts as PDF

Generate a downloadable PDF document containing selected posts with their full content, Quran references, and author information. Ayah translations are rendered according to user language preferences.

📄️ Get public post count by verse

Count public Quran Reflect posts that reference the specified Quran verse. The count is not filtered by reflection language.

📄️ Get posts by verse

Retrieve all posts written by the current user for a specific Quran verse. This endpoint requires a user-bound token and returns only the authenticated user's own posts. It is not part of the public `client_credentials`-compatible read subset; for public ayah-by-ayah reads, use `GET /v1/posts/feed` with indexed reference filters such as `filter[references][0][chapterId]`, `filter[references][0][from]`, and `filter[references][0][to]`.