docs: add User API response examples#172
Closed
basit3407 wants to merge 1 commit into
Closed
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 87f11dec15
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| @@ -1 +1 @@ | |||
| {"openapi":"3.0.0","info":{"title":"User-related APIs","version":"1.0.0","description":"Quran.Foundation user-related APIs enable your app to seamlessly integrate with Quran.Foundation's user-centric features, providing access to personalized notes, bookmarks, goals, streaks, reading sessions, and more. This differentiates them from [content APIs](/docs/category/content-apis) that focus on non-user-specific resources like translations, tafsirs, and verses.\n\n ## How to get access \n\n We are using OAuth2 flows to authenticate and authorize requests. To get started, you need to [get an access token](/docs/tutorials/oidc/getting-started-with-oauth2#obtaining-oauth-20-client-credentials) to make requests to our APIs. Then follow the steps mentioned [here](/docs/tutorials/oidc/getting-started-with-oauth2). \n\n For web applications, the recommended integration pattern is backend token exchange plus backend or server-side proxy calls to User APIs. Your app can keep the user session in secure server storage or `httpOnly` cookies, while your backend injects `x-auth-token` and `x-client-id` on outbound requests to Quran.Foundation APIs.\n\n ## Pagination \n\n We are using cursor based pagination. The pagination query params consist of `first`,`after`, `before` and `last`. \n\n Example \n - `first: 10` will give you first 10 items \n - `first: 10, after: xyz` will give you first 10 items after the item with id `xyz` \n - `last: 10` will give you the last 10 items \n - `last: 10, before: xyz` will give you the last 10 items before the item with id `xyz` \n\n The only possible combinations are `first + after` or `last + before`. They should not be used together"},"tags":[{"name":"Activity Days","description":"Track daily Quran reading activity and estimated reading time."},{"name":"Bookmarks","description":"Save, list, retrieve, and remove user bookmarks for Quran content."},{"name":"Collections","description":"Organize bookmarks into user-managed collections."},{"name":"Comments","description":"Create, list, like, and delete Quran Reflect post comments."},{"name":"Goals","description":"Create, update, delete, and estimate Quran reading goals."},{"name":"Notes","description":"Create, retrieve, update, delete, and publish personal notes and reflections."},{"name":"Posts","description":"Create, read, update, moderate, and interact with Quran Reflect posts."},{"name":"Preferences","description":"Store and retrieve user-specific app preferences."},{"name":"Reading Sessions","description":"Record and retrieve user reading progress sessions."},{"name":"Rooms","description":"Manage Quran Reflect groups, pages, membership, invites, and room posts."},{"name":"Streaks","description":"Retrieve user streak summaries and current active streak progress."},{"name":"Tags","description":"Search and retrieve Quran Reflect tags."},{"name":"Users","description":"Manage profiles, following relationships, rooms, followers, and account actions."}],"servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"components":{"securitySchemes":{"x-auth-token":{"type":"apiKey","in":"header","name":"x-auth-token","description":"The JWT access token required for accessing the endpoints."},"x-client-id":{"type":"apiKey","in":"header","name":"x-client-id","description":"Your client id"}},"schemas":{"NullableBookmark":{"type":"object","properties":{"id":{"type":"string","example":"cmpwhmp9p0005lh28bxkkf80p"},"createdAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"type":{"type":"string","example":"ayah"},"key":{"type":"integer","example":1},"verseNumber":{"type":"integer","nullable":true,"example":5},"group":{"type":"string","example":"verses_6236"},"isInDefaultCollection":{"type":"boolean","example":true},"isReading":{"type":"boolean","nullable":true,"example":false},"collectionsCount":{"type":"integer","description":"Total user-visible collection memberships for this bookmark, including Favorites when `isInDefaultCollection=true`.","example":1}},"required":["id","createdAt","type","key","group","isInDefaultCollection","isReading"],"additionalProperties":false,"nullable":true},"RawBookmark":{"type":"object","properties":{"id":{"type":"string","example":"cmpwhmp9q0006lh289ksz8c2m"},"createdAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"bookmarkType":{"oneOf":[{"type":"string","example":"ayah"},{"type":"object","properties":{"type":{"type":"string","example":"ayah"}},"required":["type"]}]},"key":{"type":"integer","example":1},"verseNumber":{"type":"integer","nullable":true,"example":5},"bookmarkGroup":{"oneOf":[{"type":"string","example":"verses_6236"},{"type":"object","properties":{"name":{"type":"string","example":"verses_6236"}},"required":["name"]}]},"isInDefaultCollection":{"type":"boolean","example":true},"isReading":{"type":"boolean","nullable":true,"example":false}},"required":["id","createdAt","bookmarkType","key","bookmarkGroup","isInDefaultCollection","isReading"]},"Bookmark":{"type":"object","properties":{"id":{"type":"string","example":"cmpwhmp9p0005lh28bxkkf80p"},"createdAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"type":{"type":"string","example":"ayah"},"key":{"type":"integer","example":1},"verseNumber":{"type":"integer","nullable":true,"example":5},"group":{"type":"string","example":"verses_6236"},"isInDefaultCollection":{"type":"boolean","example":true},"isReading":{"type":"boolean","nullable":true,"example":false},"collectionsCount":{"type":"integer","description":"Total user-visible collection memberships for this bookmark, including Favorites when `isInDefaultCollection=true`.","example":1}},"required":["id","createdAt","type","key","group","isInDefaultCollection","isReading"],"additionalProperties":false},"BookmarkWithCollectionsCount":{"type":"object","properties":{"id":{"type":"string","example":"cmpwhmp9p0005lh28bxkkf80p"},"createdAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"type":{"type":"string","example":"ayah"},"key":{"type":"integer","example":1},"verseNumber":{"type":"integer","nullable":true,"example":5},"group":{"type":"string","example":"verses_6236"},"isInDefaultCollection":{"type":"boolean","example":true},"isReading":{"type":"boolean","nullable":true,"example":false},"collectionsCount":{"type":"integer","description":"Total user-visible collection memberships for this bookmark, including Favorites when `isInDefaultCollection=true`.","example":1}},"required":["id","createdAt","type","key","group","isInDefaultCollection","isReading","collectionsCount"],"additionalProperties":false},"Collection":{"type":"object","properties":{"id":{"type":"string","example":"cmpwhmphi0008lh287hbz04ks"},"name":{"type":"string","example":"Woman in Quran"},"slug":{"type":"string","nullable":true,"example":"woman-in-quran"},"isPrivate":{"type":"boolean","example":false},"isDefault":{"type":"boolean","example":false},"modifiable":{"type":"boolean","example":true},"updatedAt":{"type":"string","format":"date-time","nullable":true,"example":"2023-01-21T07:28:13.023Z"},"url":{"type":"string","nullable":true,"example":"cmnkcpmvc000814v9f5jtbsxf"},"bookmarksCount":{"type":"integer","example":1},"resourcesCount":{"type":"integer","example":1},"count":{"type":"integer","example":1}},"required":["id","name","slug","isPrivate","isDefault","modifiable","updatedAt"],"additionalProperties":false},"EstimatedGoalTimelineDay":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"The date of the estimated day","example":"2023-01-21T07:28:13.023Z"},"amount":{"oneOf":[{"type":"string","example":"1:5-1:7"},{"type":"integer","minimum":1,"example":600}],"description":"The amount of the day's goal."}},"required":["date","amount"],"additionalProperties":false},"EstimatedGoalTimeline":{"type":"object","properties":{"week":{"type":"array","items":{"$ref":"#/components/schemas/EstimatedGoalTimelineDay"}}},"additionalProperties":false},"Preference":{"type":"object","properties":{"theme":{"type":"object","properties":{"type":{"type":"string","enum":["auto","light","sepia","dark"],"example":"auto"}},"additionalProperties":false},"reading":{"type":"object","properties":{"readingPreference":{"type":"string","enum":["translation","reading","readingTranslation"],"example":"translation"},"selectedWordByWordLocale":{"type":"string","enum":["en","ur","id","bn","tr","fa","ru","hi","de","ta","inh","fr","sq","dv","zh","sd","ml"],"example":"en"},"wordClickFunctionality":{"type":"string","enum":["play-audio","no-audio"],"example":"play-audio"},"isReadingByRevelationOrder":{"type":"boolean","example":true},"wordByWordContentType":{"type":"array","items":{"type":"string","enum":["translation","transliteration"]},"example":["translation"]},"wordByWordDisplay":{"type":"array","items":{"type":"string","enum":["tooltip","inline"]},"example":["tooltip"]},"wordByWordTooltipContentType":{"type":"array","items":{"type":"string","enum":["translation","transliteration"]},"example":["translation"]},"wordByWordInlineContentType":{"type":"array","items":{"type":"string","enum":["translation","transliteration"]},"example":[]},"selectedReadingTranslation":{"type":"string","minLength":1,"maxLength":255,"example":"131"},"selectedReflectionLanguages":{"type":"array","items":{"type":"string","maxLength":10},"minItems":1},"selectedLessonLanguages":{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}},"required":["readingPreference","selectedWordByWordLocale","wordClickFunctionality","selectedReadingTranslation"],"additionalProperties":false},"quranReaderStyles":{"type":"object","properties":{"tafsirFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"quranTextFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"translationFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"wordByWordFontScale":{"type":"integer","minimum":1,"maximum":6,"example":3},"reflectionFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"qnaFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"lessonFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"surahInfoFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"hadithFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"layersFontScale":{"type":"integer","minimum":1,"maximum":10,"example":3},"quranFont":{"type":"string","enum":["code_v1","code_v2","text_uthmani","text_indopak","qpc_uthmani_hafs","tajweed","tajweed_v4"],"example":"code_v1"},"mushafLines":{"type":"string","enum":["15_lines","16_lines"],"example":"16_lines"},"showTajweedRules":{"type":"boolean","example":true}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale","surahInfoFontScale","hadithFontScale","layersFontScale"],"additionalProperties":false},"translations":{"type":"object","properties":{"selectedTranslations":{"type":"array","items":{"type":"integer","example":131}}},"additionalProperties":false},"tafsirs":{"type":"object","properties":{"selectedTafsirs":{"type":"array","items":{"type":"string","example":"en-tafisr-ibn-kathir"}}},"additionalProperties":false},"audio":{"type":"object","properties":{"reciter":{"type":"integer","example":7},"playbackRate":{"type":"integer","enum":[0.25,0.5,0.75,1,1.25,1.5,1.75,2],"example":1},"showTooltipWhenPlayingAudio":{"type":"boolean","example":true},"enableAutoScrolling":{"type":"boolean","example":true}},"required":["reciter"],"additionalProperties":false},"language":{"type":"object","properties":{"language":{"type":"string","enum":["en","ar","bn","fa","fr","id","it","nl","pt","ru","sq","th","tr","ur","zh","ms","es","sw","vi"]}},"additionalProperties":false},"userHasCustomised":{"type":"object","properties":{"userHasCustomised":{"type":"boolean","example":false}},"required":["userHasCustomised"],"additionalProperties":false}},"additionalProperties":false},"ReadingSession":{"type":"object","properties":{"id":{"type":"string","example":"cmpwhmqau000klh285fxud33f"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"chapterNumber":{"type":"integer","example":1},"verseNumber":{"type":"integer","example":5}},"required":["id","updatedAt"],"additionalProperties":false},"UserProfile":{"type":"object","properties":{"id":{"type":"string"},"createdAt":{"type":"string","format":"date-time","example":"2022-12-06T06:16:20.229Z"},"email":{"type":"string","example":"muhajir@quran.com"},"firstName":{"type":"string","example":"Muhammad"},"lastName":{"type":"string","example":"Muhajir"},"username":{"type":"string","example":"muhajir"},"photoUrl":{"type":"string","example":"https://photos.quran.com/img/muhajir.jpg"},"isAdmin":{"type":"boolean","example":false},"isPasswordSet":{"type":"boolean","example":true}},"additionalProperties":false},"EditProfileDto":{"type":"object","properties":{"languageId":{"type":"number"},"reflectionLanguages":{"type":"array","items":{"type":"string"}},"ayahLanguages":{"type":"array","items":{"type":"string"}},"customized":{"type":"boolean","default":false},"hideFollowSuggestion":{"type":"boolean","description":"Hide follow suggestion popup after liking a post"},"showFollowFeaturedSuggestion":{"type":"boolean","description":"Show featured follow suggestion popup on QR onboarding"}}},"UserProfileSettingsDto":{"type":"object","properties":{"ayahLanguages":{"type":"array","items":{"type":"number"}},"reflectionLanguages":{"type":"array","items":{"type":"number"}},"customized":{"type":"boolean"},"hideFollowSuggestion":{"type":"boolean","description":"Hide follow suggestion popup after liking a post"},"showFollowFeaturedSuggestion":{"type":"boolean","description":"Show featured follow suggestion popup on Quran Reflect onboarding"}}},"UserProfileResponseDto":{"type":"object","properties":{"avatarUrls":{"type":"object","example":{"small":"https://avatars.githubusercontent.com/u/12345678","medium":"https://avatars.githubusercontent.com/u/12345678","large":"https://avatars.githubusercontent.com/u/12345678"}},"settings":{"description":"Quran Reflect user settings. showFollowFeaturedSuggestion defaults to false.","allOf":[{"$ref":"#/components/schemas/UserProfileSettingsDto"}]},"createdAt":{"type":"string","example":"2000-01-21 00:00:00"},"joiningYear":{"type":"number","example":2025},"isPasswordSet":{"type":"boolean","description":"Only returned when qdc=true and the Quran.com connected account lookup succeeds.","example":true},"email":{"type":"string","description":"Only returned when qdc=true and the Quran.com connected account lookup succeeds.","example":"user@example.com"},"photoUrl":{"type":"string","description":"Only returned when qdc=true and the Quran.com connected account lookup succeeds.","example":"https://photos.quran.com/img/user.jpg"},"username":{"type":"string"},"id":{"type":"string"},"verified":{"type":"boolean","default":false},"postAs":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"postsCount":{"type":"number","default":0},"languageId":{"type":"number"},"followersCount":{"type":"number","default":0},"likesCount":{"type":"number","default":0},"isAdmin":{"type":"boolean","default":false},"languageIsoCode":{"type":"string","default":"en"},"bio":{"type":"string"},"country":{"type":"string"},"followed":{"type":"boolean"}},"required":["avatarUrls","settings","createdAt","joiningYear","id"]},"UpdateProfileDto":{"type":"object","properties":{"avatar":{"type":"string","pattern":"/^data:image\\/[a-z]+;base64,/"},"firstName":{"type":"string"},"lastName":{"type":"string"},"bio":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"removeAvatar":{"type":"boolean"}}},"UpdateProfileBodyDto":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/UpdateProfileDto"}},"required":["user"]},"UserSerializedDto":{"type":"object","properties":{"avatarUrls":{"type":"object","example":{"small":"https://avatars.githubusercontent.com/u/12345678","medium":"https://avatars.githubusercontent.com/u/12345678","large":"https://avatars.githubusercontent.com/u/12345678"}},"settings":{"description":"Quran Reflect user settings. showFollowFeaturedSuggestion defaults to false.","allOf":[{"$ref":"#/components/schemas/UserProfileSettingsDto"}]},"createdAt":{"type":"string","example":"2000-01-21 00:00:00"},"joiningYear":{"type":"number","example":2025},"username":{"type":"string"},"id":{"type":"string"},"verified":{"type":"boolean","default":false},"postAs":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"postsCount":{"type":"number","default":0},"languageId":{"type":"number"},"followersCount":{"type":"number","default":0},"likesCount":{"type":"number","default":0},"isAdmin":{"type":"boolean","default":false},"languageIsoCode":{"type":"string","default":"en"},"bio":{"type":"string"},"country":{"type":"string"},"followed":{"type":"boolean"}},"required":["avatarUrls","settings","createdAt","joiningYear","id"]},"UserRoomDto":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"group":{"type":"string"},"public":{"type":"boolean"},"roomType":{"type":"string"},"verified":{"type":"boolean"},"subdomain":{"type":"string"},"description":{"type":"string"},"membersCount":{"type":"number"},"avatarUrl":{"type":"object","properties":{"small":{"required":true,"type":"string"},"medium":{"required":true,"type":"string"},"large":{"required":true,"type":"string"}}}},"required":["id","name","group","public","roomType","verified","subdomain","description","membersCount","avatarUrl"]},"UserRoomsResponse":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/UserRoomDto"}}},"required":["total","currentPage","limit","pages","data"]},"UserSearchDto":{"type":"object","properties":{"id":{"type":"string","example":"8d77a633-b49d-4978-bc1a-70bc2fda7b4b"},"username":{"type":"string"},"verified":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"avatarUrls":{"type":"object","example":{"small":"https://avatars.githubusercontent.com/u/12345678","medium":"https://avatars.githubusercontent.com/u/12345678","large":"https://avatars.githubusercontent.com/u/12345678"}},"followersCount":{"type":"number","default":0},"bio":{"type":"string"},"isFollowed":{"type":"boolean","example":false},"followed":{"type":"boolean","example":false}},"required":["id","avatarUrls","isFollowed"]},"UsersSearchResponse":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/UserSearchDto"}}},"required":["total","currentPage","limit","pages","data"]},"ToggleFollowDto":{"type":"object","properties":{"action":{"enum":["follow","unfollow"],"type":"string","description":"The intended action: follow or unfollow","example":"follow"}}},"FeaturedUserDto":{"type":"object","properties":{"id":{"type":"string","example":"1f8d6f3f-2f57-4c3e-b7b5-5f6a9d7f7a55"},"username":{"type":"string","example":"example.user"},"verified":{"type":"boolean","example":true},"firstName":{"type":"string","example":"Example"},"lastName":{"type":"string","example":"User"},"fullName":{"type":"string","example":"Example User"},"avatarUrls":{"type":"object","example":{"small":"https://avatars.githubusercontent.com/u/12345678","medium":"https://avatars.githubusercontent.com/u/12345678","large":"https://avatars.githubusercontent.com/u/12345678"}},"followersCount":{"type":"number","example":1200},"bio":{"type":"string","example":"I write reflections on the Quran."}},"required":["id","username","verified","firstName","lastName","fullName","avatarUrls","followersCount"]},"FeaturedUsersResponseDto":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/FeaturedUserDto"}}},"required":["total","currentPage","limit","pages","data"]},"FailedFeaturedFollowItemDto":{"type":"object","properties":{"followeeId":{"type":"string","example":"user-id-123"},"reason":{"type":"string","example":"FOLLOW_FAILED"}},"required":["followeeId","reason"]},"FollowFeaturedUsersResponseDto":{"type":"object","properties":{"requested":{"type":"number","example":9},"followed":{"type":"number","example":7},"skipped":{"type":"number","example":1},"failed":{"type":"number","example":1},"complete":{"type":"boolean","example":true},"failedItems":{"type":"array","items":{"$ref":"#/components/schemas/FailedFeaturedFollowItemDto"}}},"required":["requested","followed","skipped","failed","complete"]},"OtherUserProfileDto":{"type":"object","properties":{"avatarUrls":{"type":"object","example":{"small":"https://avatars.githubusercontent.com/u/12345678","medium":"https://avatars.githubusercontent.com/u/12345678","large":"https://avatars.githubusercontent.com/u/12345678"}},"settings":{"description":"Quran Reflect user settings. showFollowFeaturedSuggestion defaults to false.","allOf":[{"$ref":"#/components/schemas/UserProfileSettingsDto"}]},"createdAt":{"type":"string","example":"2000-01-21 00:00:00"},"joiningYear":{"type":"number","example":2025},"followed":{"type":"boolean","description":"Whether the authenticated viewer follows this user.","example":false},"mutualFollowers":{"description":"Only returned when the viewer is authenticated.","type":"array","items":{"$ref":"#/components/schemas/UserSerializedDto"}},"mutualFollowersCount":{"type":"number","description":"Only returned when the viewer is authenticated.","example":2},"username":{"type":"string"},"id":{"type":"string"},"verified":{"type":"boolean","default":false},"postAs":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"postsCount":{"type":"number","default":0},"languageId":{"type":"number"},"followersCount":{"type":"number","default":0},"likesCount":{"type":"number","default":0},"isAdmin":{"type":"boolean","default":false},"languageIsoCode":{"type":"string","default":"en"},"bio":{"type":"string"},"country":{"type":"string"}},"required":["avatarUrls","settings","createdAt","joiningYear","id"]},"UserProfileListItemDto":{"type":"object","properties":{"avatarUrls":{"type":"object","example":{"small":"https://avatars.githubusercontent.com/u/12345678","medium":"https://avatars.githubusercontent.com/u/12345678","large":"https://avatars.githubusercontent.com/u/12345678"}},"settings":{"description":"Quran Reflect user settings. showFollowFeaturedSuggestion defaults to false.","allOf":[{"$ref":"#/components/schemas/UserProfileSettingsDto"}]},"createdAt":{"type":"string","example":"2000-01-21 00:00:00"},"joiningYear":{"type":"number","example":2025},"followed":{"type":"boolean","example":false},"username":{"type":"string"},"id":{"type":"string"},"verified":{"type":"boolean","default":false},"postAs":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"postsCount":{"type":"number","default":0},"languageId":{"type":"number"},"followersCount":{"type":"number","default":0},"likesCount":{"type":"number","default":0},"isAdmin":{"type":"boolean","default":false},"languageIsoCode":{"type":"string","default":"en"},"bio":{"type":"string"},"country":{"type":"string"}},"required":["avatarUrls","settings","createdAt","joiningYear","id"]},"UsersProfileListResponse":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/UserProfileListItemDto"}}},"required":["total","currentPage","limit","pages","data"]},"RoomAdminUpdateDto":{"type":"object","properties":{"roomId":{"type":"number"},"userId":{"type":"string"},"admin":{"type":"boolean"}},"required":["roomId","userId","admin"]},"UpdateGroupDto":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","maxLength":200},"url":{"type":"string","minLength":1,"maxLength":50},"removeAvatar":{"type":"boolean"},"avatar":{"type":"string","pattern":"/^data:image\\/[a-z]+;base64,/"},"country":{"type":"string","nullable":true},"public":{"type":"boolean","nullable":true,"default":null},"hideFollowJoinButton":{"type":"boolean","nullable":true,"default":null}},"required":["id"]},"UpdatePageDto":{"type":"object","properties":{"id":{"type":"number"},"removeAvatar":{"type":"boolean"},"avatar":{"type":"string","pattern":"/^data:image\\/[a-z]+;base64,/"},"public":{"type":"boolean","nullable":true,"default":null},"hideFollowJoinButton":{"type":"boolean","nullable":true,"default":null},"name":{"type":"string"},"description":{"type":"string"},"organizationWebsite":{"type":"string"},"country":{"type":"string"},"url":{"type":"string"}},"required":["id"]},"MemberSerializedDto":{"type":"object","properties":{"id":{"type":"string","example":"user-1"},"username":{"type":"string","example":"member.username"},"firstName":{"type":"string","example":"Member"},"lastName":{"type":"string","example":"User"},"verified":{"type":"boolean","example":true},"avatarUrls":{"type":"object","example":{"small":"https://avatars.quran.foundation/users/user-1/small.png","medium":"https://avatars.quran.foundation/users/user-1/medium.png","large":"https://avatars.quran.foundation/users/user-1/large.png"}},"isAdmin":{"type":"boolean","example":false},"isOwner":{"type":"boolean","example":false},"isFollowed":{"type":"boolean","example":true},"isActive":{"type":"boolean","example":true},"followersCount":{"type":"number","example":42}},"required":["id","username","firstName","lastName","verified","avatarUrls","isAdmin","isOwner","isFollowed","isActive","followersCount"]},"RoomMembersResponseDto":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/MemberSerializedDto"}}},"required":["total","currentPage","limit","pages","data"]},"InviteUserDto":{"type":"object","properties":{"userIds":{"type":"array","items":{"type":"string"}},"emails":{"type":"array","items":{"type":"string"}}},"required":["userIds","emails"]},"RoomInviteUserResponseDto":{"type":"object","properties":{"invited":{"type":"boolean","example":true},"inviteStatus":{"type":"object","additionalProperties":{"oneOf":[{"type":"boolean"},{"type":"string"}]},"example":{"user-123":true,"user-456":"already_a_member"}}},"required":["invited","inviteStatus"]},"RoomInviteAcceptedResponseDto":{"type":"object","properties":{"accepted":{"type":"boolean","example":true}},"required":["accepted"]},"RoomInviteRejectedResponseDto":{"type":"object","properties":{"rejected":{"type":"boolean","example":true}},"required":["rejected"]},"CreatePageDto":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"jobTitle":{"type":"string"},"contactNumber":{"type":"string"},"organizationName":{"type":"string"},"organizationWebsite":{"type":"string"},"purpose":{"type":"string"},"additionalDetails":{"type":"string"},"country":{"type":"string"},"url":{"type":"string"},"public":{"type":"boolean"},"hideFollowJoinButton":{"type":"boolean"}},"required":["name","jobTitle","contactNumber","organizationName","purpose","url"]},"CreateGroupDto":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50},"description":{"type":"string","maxLength":200},"url":{"type":"string","minLength":1,"maxLength":50},"public":{"type":"boolean"},"hideFollowJoinButton":{"type":"boolean"}},"required":["name","url"]},"RoomListItemDto":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"roomType":{"type":"string"},"isActive":{"type":"boolean"},"isVerified":{"type":"boolean"},"isPublic":{"type":"boolean"},"hideFollowJoinButton":{"type":"boolean"},"isOwner":{"type":"boolean"},"isAdmin":{"type":"boolean"},"ownerId":{"type":"string"},"postsCount":{"type":"number"},"membersCount":{"type":"number"},"url":{"type":"string"},"avatarUrls":{"type":"object","properties":{"thumb":{"required":true,"type":"string"},"original":{"required":true,"type":"string"}}},"createdAt":{"format":"date-time","type":"string"},"isMember":{"type":"boolean"},"subdomain":{"type":"string"},"country":{"type":"string"}},"required":["id","name","description","roomType","isActive","isVerified","isPublic","hideFollowJoinButton","isOwner","isAdmin","ownerId","postsCount","membersCount","avatarUrls"]},"RoomCreatedResponseDto":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/RoomListItemDto"}},"required":["success","data"]},"PaginatedRoomsResponseDto":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/RoomListItemDto"}}},"required":["total","currentPage","limit","pages","data"]},"RoomProfileResponseDto":{"type":"object","properties":{"privateToken":{"type":"string","example":"private-room-token"},"mutualFollowers":{"type":"array","items":{"$ref":"#/components/schemas/UserSerializedDto"}},"mutualFollowersCount":{"type":"number","example":2},"id":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"},"roomType":{"type":"string"},"isActive":{"type":"boolean"},"isVerified":{"type":"boolean"},"isPublic":{"type":"boolean"},"hideFollowJoinButton":{"type":"boolean"},"isOwner":{"type":"boolean"},"isAdmin":{"type":"boolean"},"ownerId":{"type":"string"},"postsCount":{"type":"number"},"membersCount":{"type":"number"},"url":{"type":"string"},"avatarUrls":{"type":"object","properties":{"thumb":{"required":true,"type":"string"},"original":{"required":true,"type":"string"}}},"createdAt":{"format":"date-time","type":"string"},"isMember":{"type":"boolean"},"subdomain":{"type":"string"},"country":{"type":"string"}},"required":["id","name","description","roomType","isActive","isVerified","isPublic","hideFollowJoinButton","isOwner","isAdmin","ownerId","postsCount","membersCount","avatarUrls"]},"RoomAcceptByPrivateTokenResponseDto":{"type":"object","properties":{"roomId":{"type":"number","example":42},"success":{"type":"boolean","example":true},"isNewMember":{"type":"boolean","example":true}},"required":["roomId","success","isNewMember"]},"PostTag":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"]},"PostReference":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"]},"UserAuthor":{"type":"object","properties":{"postsCount":{"type":"number"},"avatarUrls":{"type":"object","properties":{"small":{"required":true,"type":"string"},"medium":{"required":true,"type":"string"},"large":{"required":true,"type":"string"}}},"id":{"type":"string"},"username":{"type":"string"},"verified":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"memberType":{"type":"number"}},"required":["avatarUrls","id"]},"PostRecentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"$ref":"#/components/schemas/UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"]},"PostRoom":{"type":"object","properties":{"isAdmin":{"type":"object"},"isOwner":{"type":"object"},"isPublic":{"type":"object"},"id":{"type":"number"},"subdomain":{"type":"string"},"roomType":{"type":"string"},"verified":{"type":"boolean","default":false},"name":{"type":"string"},"_group":{"type":"string"}},"required":["id"]},"UserWithMentionLocations":{"type":"object","properties":{"postsCount":{"type":"number"},"avatarUrls":{"type":"object","properties":{"small":{"required":true,"type":"string"},"medium":{"required":true,"type":"string"},"large":{"required":true,"type":"string"}}},"id":{"type":"string"},"username":{"type":"string"},"verified":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"memberType":{"type":"number"},"locations":{"type":"object"},"followersCount":{"type":"number"},"displayName":{"type":"string"}},"required":["avatarUrls","id","locations","followersCount"]},"PostSerialized":{"type":"object","properties":{"tags":{"type":"array","items":{"$ref":"#/components/schemas/PostTag"}},"references":{"type":"array","items":{"$ref":"#/components/schemas/PostReference"}},"author":{"type":"object"},"recentComment":{"$ref":"#/components/schemas/PostRecentComment"},"room":{"nullable":true,"allOf":[{"$ref":"#/components/schemas/PostRoom"}]},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/UserWithMentionLocations"}},"isLiked":{"type":"boolean"},"isByFollowedUser":{"type":"boolean"},"isCommentedOn":{"type":"boolean"},"isSaved":{"type":"boolean"},"id":{"type":"number"},"authorId":{"type":"string"},"body":{"type":"string"},"discussionId":{"type":"number"},"draft":{"type":"boolean","default":false},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"publishedAt":{"format":"date-time","type":"string"},"global":{"type":"boolean"},"toxicityScore":{"type":"number"},"reported":{"type":"boolean","default":false},"views":{"type":"number"},"removed":{"type":"boolean","default":false},"verified":{"type":"boolean","default":false},"roomPostStatus":{"description":"@description 0: OnlyMembers, 1: Publicly, 2: AsRoom","default":0,"enum":[0,1,2],"type":"number"},"hidden":{"type":"boolean","default":false},"commentsCount":{"type":"number","default":0},"likesCount":{"type":"number","default":0},"viewsCount":{"type":"number","default":0},"languageId":{"type":"number"},"languageName":{"type":"string"},"moderationStatus":{"description":"featured = 1, // Like Sticky posts, will be featured for a time period.Shown at top in feed and partner apps\n\npromoted = 2, // High quality content.Shown at top(after featured) in feed and partner apps\n\nnormal = 3, // Default status, available in search, latest and popular tabs.In feed(if you're following the author)\n\nhidden = 4, // Visible only to author or moderators, or via private share link.\n\nprivate_note = 5, // Private notes, only visible to author or via private share link.These are the posts made \"private\" by moderators.\n\nrequested_review = 6, // User requested the review, treat them has hidden.Only visible to author and moderators\n\ndeleted = 30,","enum":[1,2,3,4,5,6,30],"type":"number"},"reviewedAt":{"format":"date-time","type":"string"},"featuredAt":{"format":"date-time","type":"string"},"pushedUpAt":{"format":"date-time","type":"string"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"]},"FeedResponseDto":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"data":{"type":"array","items":{"$ref":"#/components/schemas/PostSerialized"}}},"required":["total","currentPage","limit","pages","data"]},"RoomPostUpdatePrivacyDto":{"type":"object","properties":{"isPublic":{"type":"boolean"}},"required":["isPublic"]},"ReferenceAttributes":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"]},"UserMentionAttributes":{"type":"object","properties":{"marker":{"type":"string","pattern":"/{{[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}}}/","example":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}"},"userId":{"type":"string"},"displayName":{"type":"string"}},"required":["marker","userId","displayName"]},"CreatePostDto":{"type":"object","properties":{"roomPostStatus":{"enum":[0,1,2],"type":"number","description":"The room post status, defaults to publicly: 1. As Room: 0, Publicly: 1, Only Members: 2"},"body":{"type":"string","minLength":6},"draft":{"type":"boolean"},"references":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceAttributes"}},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"]},"CreatePostBodyDto":{"type":"object","properties":{"post":{"$ref":"#/components/schemas/CreatePostDto"}},"required":["post"]},"PostCreatedResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PostSerialized"},"success":{"type":"boolean"}},"required":["data","success"]},"UpdatePostDto":{"type":"object","properties":{"roomPostStatus":{"enum":[0,1,2],"type":"number","description":"The room post status, defaults to publicly: 1. As Room: 0, Publicly: 1, Only Members: 2"},"body":{"type":"string","minLength":6},"draft":{"type":"boolean"},"references":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceAttributes"}},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}}},"ReportAbuseDto":{"type":"object","properties":{"abuse":{"type":"string"},"comments":{"type":"string"}},"required":["abuse"]},"ReportAbuseBodyDto":{"type":"object","properties":{"report":{"$ref":"#/components/schemas/ReportAbuseDto"}},"required":["report"]},"CommentAuthor":{"type":"object","properties":{"postsCount":{"type":"number"},"avatarUrls":{"type":"object","properties":{"small":{"required":true,"type":"string"},"medium":{"required":true,"type":"string"},"large":{"required":true,"type":"string"}}},"id":{"type":"string"},"username":{"type":"string"},"verified":{"type":"boolean","default":false},"firstName":{"type":"string"},"lastName":{"type":"string"},"memberType":{"type":"number"}},"required":["avatarUrls","id"]},"CommentTag":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"},"commentsCount":{"type":"number"}},"required":["id"]},"Comment":{"type":"object","properties":{"id":{"type":"number"},"postId":{"type":"number"},"authorId":{"type":"string"},"parentId":{"type":"number"},"isPrivate":{"type":"boolean","default":false},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"toxicityScore":{"type":"number"},"repliesCount":{"type":"number","default":0},"likesCount":{"type":"number","default":0},"reported":{"type":"boolean","default":false},"removed":{"type":"boolean","default":false},"hidden":{"type":"boolean","default":false},"languageId":{"type":"number"},"languageName":{"type":"string"},"moderationStatus":{"type":"number"},"author":{"$ref":"#/components/schemas/CommentAuthor"},"mentions":{"type":"array","items":{"$ref":"#/components/schemas/UserWithMentionLocations"}},"tags":{"type":"array","items":{"$ref":"#/components/schemas/CommentTag"}}},"required":["id","postId","authorId","parentId","isPrivate","body","createdAt","updatedAt"]},"PostCommentsResponse":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"comments":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}}},"required":["total","currentPage","limit","pages","comments"]},"PostAllCommentsResponse":{"type":"object","properties":{"comments":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}},"total":{"type":"number","example":"10 // works also with swagger setup"}},"required":["comments","total"]},"ExportPostsDto":{"type":"object","properties":{"ids":{"description":"Array of post IDs to export","example":[1,2,3],"minItems":1,"type":"array","items":{"type":"number"}}},"required":["ids"]},"Tag":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"rank":{"type":"number","default":0},"languageId":{"type":"number"},"languageName":{"type":"string"},"postsCount":{"type":"number"},"commentsCount":{"type":"number"}},"required":["id","createdAt","updatedAt"]},"CreateCommentDto":{"type":"object","properties":{"body":{"type":"string","description":"Comment body text","example":"This is a thoughtful comment about the post","maxLength":8000},"postId":{"type":"number","description":"ID of the post this comment belongs to","example":123},"isPrivate":{"type":"boolean","default":false,"description":"Whether the comment is private","example":false},"parentId":{"type":"number","description":"ID of the parent comment (for replies)","example":456},"mentions":{"description":"User mentions in the comment","type":"array","items":{"$ref":"#/components/schemas/UserMentionAttributes"}}},"required":["body","postId","isPrivate"]},"CreateCommentBody":{"type":"object","properties":{"comment":{"description":"Comment details for creation","allOf":[{"$ref":"#/components/schemas/CreateCommentDto"}]}},"required":["comment"]},"CreateCommentResponse":{"type":"object","properties":{"comment":{"$ref":"#/components/schemas/Comment"},"success":{"type":"boolean"}},"required":["comment","success"]},"CommentRepliesResponse":{"type":"object","properties":{"total":{"type":"number","example":10},"currentPage":{"type":"number","example":1},"limit":{"type":"number","example":10},"pages":{"type":"number","example":1},"replies":{"type":"array","items":{"$ref":"#/components/schemas/Comment"}},"comment":{"$ref":"#/components/schemas/Comment"}},"required":["total","currentPage","limit","pages","replies","comment"]}},"responses":{}},"security":[{"x-auth-token":[],"x-client-id":[]}],"paths":{"/v1/collections":{"post":{"description":"Create a new collection under user's account.","tags":["Collections"],"summary":"Add collection","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The name of the new collection to be created.","example":"Woman in Quran"},"clientCreatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:15:30.000Z"},"clientUpdatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:16:30.000Z"}},"required":["name"],"additionalProperties":false},"example":{"name":"Woman in Quran","clientCreatedAt":"2026-05-19T10:15:30.000Z","clientUpdatedAt":"2026-05-19T10:16:30.000Z"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Collection"}},"additionalProperties":false},"example":{"success":true,"data":{"id":"cmpwhmphi0008lh287hbz04ks","name":"Woman in Quran","slug":"woman-in-quran","isPrivate":false,"isDefault":false,"modifiable":true,"updatedAt":"2023-01-21T07:28:13.023Z","url":"cmnkcpmvc000814v9f5jtbsxf","bookmarksCount":1,"resourcesCount":1,"count":1}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1Collections"},"get":{"tags":["Collections"],"description":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","summary":"Get all collections","parameters":[{"in":"query","name":"sortBy","schema":{"type":"string","enum":["recentlyUpdated","alphabetical"],"description":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","example":"recentlyUpdated"},"description":"Sort the collections list either by the time they were updated at descendingly or alphabetically."},{"in":"query","name":"type","schema":{"type":"string","enum":["page","juz","surah","ayah"],"description":"Filter collections to ones with bookmarks of this type."},"description":"Filter collections to ones with bookmarks of this type."},{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":[{"id":"cmpwhmphi0008lh287hbz04ks","name":"Woman in Quran","slug":"woman-in-quran","isPrivate":false,"isDefault":false,"modifiable":true,"updatedAt":"2023-01-21T07:28:13.023Z","url":"cmnkcpmvc000814v9f5jtbsxf","bookmarksCount":1,"resourcesCount":1,"count":1}],"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1Collections"}},"/v1/collections/{collectionId}/bookmarks":{"post":{"description":"Add a bookmark to a collection. Use `collectionId=\"__default__\"` to add an ayah bookmark to the virtual Favorites collection used by Quran.com.","tags":["Collections"],"summary":"Add collection Bookmark","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The collection ID. Use `__default__` to add an ayah bookmark to the virtual Favorites collection used by Quran.com.","example":"cmpwhmpm50009lh28e5pe2sqr"},"required":true,"description":"The collection ID. Use `__default__` to add an ayah bookmark to the virtual Favorites collection used by Quran.com."}],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"key":{"type":"integer","description":"The Surah number.","example":2},"type":{"type":"string","enum":["ayah"],"description":"The bookmark type.","default":"ayah"},"verseNumber":{"type":"integer","example":3},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name.","example":4},"mushaf":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`.","example":4},"clientCreatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:15:30.000Z"},"clientUpdatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:16:30.000Z"}},"required":["key","verseNumber"],"additionalProperties":false,"title":"Ayah"},{"type":"object","properties":{"key":{"type":"integer","description":"Surah, Juz or page number."},"type":{"type":"string","enum":["juz","page","surah"],"description":"The bookmark type.","example":"surah"},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name.","example":4},"mushaf":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`.","example":4},"clientCreatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:15:30.000Z"},"clientUpdatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:16:30.000Z"}},"required":["key"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]},"example":{"key":2,"type":"ayah","verseNumber":3,"mushafId":4,"mushaf":4,"clientCreatedAt":"2026-05-19T10:15:30.000Z","clientUpdatedAt":"2026-05-19T10:16:30.000Z"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["collection bookmark added"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"collection bookmark added"}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1CollectionsByCollectionIdBookmarks"},"delete":{"description":"Delete a bookmark from a collection by bookmark details. Use `collectionId=\"__default__\"` to remove a bookmark from the virtual Favorites collection. When successfully deleted, the bookmark itself is only detached from the collection unless it becomes an orphan.","tags":["Collections"],"summary":"Delete collection bookmark by details","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The collection ID. Use `__default__` to remove a bookmark from the virtual Favorites collection.","example":"cmpwhmpod000clh280sx8039s"},"required":true,"description":"The collection ID. Use `__default__` to remove a bookmark from the virtual Favorites collection."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"additionalProperties":false},"example":{"success":true,"data":{}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"key":{"type":"integer","description":"Surah number","example":2},"type":{"type":"string","enum":["ayah"],"description":"The bookmark type.","default":"ayah"},"verseNumber":{"type":"integer","example":3},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name.","example":4},"mushaf":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`.","example":4}},"required":["key","verseNumber"],"additionalProperties":false,"title":"Ayah"},{"type":"object","properties":{"key":{"type":"integer","description":"Surah, Juz or page number."},"type":{"type":"string","enum":["juz","page","surah"],"description":"The bookmark type.","example":"surah"},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name.","example":4},"mushaf":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`.","example":4}},"required":["key"],"additionalProperties":false,"title":"Surah, Juz, Or Page"},{"type":"object","properties":{"bookmarkId":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmpwhmpoc000blh2810gv4tmd"}},"required":["bookmarkId"],"additionalProperties":false,"title":"Bookmark ID"}],"title":"input"},"example":{"key":2,"type":"ayah","verseNumber":3,"mushafId":4,"mushaf":4}}}},"operationId":"authDeleteV1CollectionsByCollectionIdBookmarks"}},"/v1/collections/{collectionId}":{"delete":{"description":"Delete a an existing collection.","tags":["Collections"],"summary":"Delete collection","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmpwhmpmy000alh286eama92w"},"required":true,"description":"The Id of the collection to be deleted."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["collection deleted"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"collection deleted"}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authDeleteV1CollectionsByCollectionId"},"get":{"description":"Get all resources that belong to an existing collection by collection id. Use `__default__` to fetch the virtual Favorites collection.","tags":["Collections"],"summary":"Get collection items by id","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"Collection ID. Use `__default__` for the virtual Favorites collection.","example":"cmpwhmprc000flh285db07pmv"},"description":"Collection ID. Use `__default__` for the virtual Favorites collection."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["recentlyAdded","verseKey"],"description":"Sort the collection items either by the time they were added at descendingly or by Ayah key."},"description":"Sort the collection items either by the time they were added at descendingly or by Ayah key."},{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"collection":{"$ref":"#/components/schemas/Collection"},"bookmarks":{"type":"array","items":{"$ref":"#/components/schemas/BookmarkWithCollectionsCount"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"collection":{"id":"cmpwhmphi0008lh287hbz04ks","name":"Woman in Quran","slug":"woman-in-quran","isPrivate":false,"isDefault":false,"modifiable":true,"updatedAt":"2023-01-21T07:28:13.023Z","url":"cmnkcpmvc000814v9f5jtbsxf","bookmarksCount":1,"resourcesCount":1,"count":1},"bookmarks":[{"id":"cmpwhmp9p0005lh28bxkkf80p","createdAt":"2023-01-21T07:28:13.023Z","type":"ayah","key":1,"verseNumber":5,"group":"verses_6236","isInDefaultCollection":true,"isReading":false,"collectionsCount":1}]},"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1CollectionsByCollectionId"},"post":{"description":"Update an existing collection.","tags":["Collections"],"summary":"Update collection","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be updated."},"required":true,"description":"The Id of the collection to be updated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the collection to be updated."},"clientUpdatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:16:30.000Z"}},"required":["name"],"additionalProperties":false},"example":{"name":"string","clientUpdatedAt":"2026-05-19T10:16:30.000Z"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"collection renamed"}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1CollectionsByCollectionId"}},"/v1/collections/{collectionId}/bookmarks/{bookmarkId}":{"delete":{"description":"Delete a bookmark from a collection by bookmark ID. Use `collectionId=\"__default__\"` to remove a bookmark from the virtual Favorites collection. When successfully deleted, the bookmark itself is only detached from the collection unless it becomes an orphan.","tags":["Collections"],"summary":"Delete collection bookmark by id","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The collection ID. Use `__default__` to remove a bookmark from the virtual Favorites collection.","example":"cmpwhmpph000dlh284pn9dv5h"},"required":true,"description":"The collection ID. Use `__default__` to remove a bookmark from the virtual Favorites collection."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmpwhmpph000elh28h42ud5up"},"required":true,"description":"The Id of the bookmark to be deleted."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["collection bookmark deleted"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"collection bookmark deleted"}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authDeleteV1CollectionsByCollectionIdBookmarksByBookmarkId"}},"/v1/collections/all":{"get":{"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"summary":"Get all collection items","parameters":[{"in":"query","name":"sortBy","schema":{"type":"string","enum":["recentlyAdded","verseKey"],"description":"Sort the collection items either by the time they were added at descendingly or alphabetically."},"description":"Sort the collection items either by the time they were added at descendingly or alphabetically."},{"in":"query","name":"type","schema":{"type":"string","enum":["page","juz","surah","ayah"],"description":"The bookmark type.","default":"ayah"},"description":"The bookmark type."},{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":[{"id":"cmpwhmp9p0005lh28bxkkf80p","createdAt":"2023-01-21T07:28:13.023Z","type":"ayah","key":1,"verseNumber":5,"group":"verses_6236","isInDefaultCollection":true,"isReading":false,"collectionsCount":1}],"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1CollectionsAll"}},"/v1/bookmarks":{"post":{"description":"Add or update a bookmark by details. Omit `isReading` to create or update a regular standalone bookmark. Set `isReading=true` to set the user's singleton reading bookmark and replace any previous reading bookmark. Set `isReading=false` or `null` to mark this bookmark as non-reading. For Quran.com-style saved or favorite ayah bookmarks, use `POST /v1/collections/__default__/bookmarks`.","tags":["Bookmarks"],"summary":"Add user bookmark","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"key":{"type":"integer","description":"The Surah number.","example":2},"type":{"type":"string","enum":["ayah"],"description":"The bookmark type.","default":"ayah"},"verseNumber":{"type":"integer","description":"The Ayah number to be added.","example":3},"isReading":{"type":"boolean","nullable":true,"description":"Reading bookmark flag. Set `true` to set the user's current reading bookmark. Set `false` or `null` to mark this bookmark as non-reading. Omit this field to create or update a regular bookmark."},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name.","example":4},"mushaf":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`.","example":4},"clientCreatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:15:30.000Z"},"clientUpdatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:16:30.000Z"}},"required":["key","type","verseNumber"],"additionalProperties":false,"title":"Ayah"},{"type":"object","properties":{"key":{"type":"integer","description":"Surah, Juz or page number."},"type":{"type":"string","enum":["juz","page","surah"],"description":"The bookmark type.","example":"surah"},"isReading":{"type":"boolean","nullable":true,"description":"Reading bookmark flag. Set `true` to set the user's current reading bookmark. Set `false` or `null` to mark this bookmark as non-reading. Omit this field to create or update a regular bookmark."},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name.","example":4},"mushaf":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`.","example":4},"clientCreatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:15:30.000Z"},"clientUpdatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:16:30.000Z"}},"required":["key","type"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]},"example":{"key":2,"type":"ayah","verseNumber":3,"isReading":true,"mushafId":4,"mushaf":4,"clientCreatedAt":"2026-05-19T10:15:30.000Z","clientUpdatedAt":"2026-05-19T10:16:30.000Z"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/NullableBookmark"}},"additionalProperties":false},"example":{"success":true,"data":{"id":"cmpwhmp9p0005lh28bxkkf80p","createdAt":"2023-01-21T07:28:13.023Z","type":"ayah","key":1,"verseNumber":5,"group":"verses_6236","isInDefaultCollection":true,"isReading":false,"collectionsCount":1}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1Bookmarks"},"get":{"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["Bookmarks"],"summary":"Get user bookmarks","parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["page","juz","surah","ayah"],"description":"The bookmark type.","default":"ayah"},"required":false,"description":"The bookmark type."},{"in":"query","name":"isReading","schema":{"type":"boolean","description":"Whether to fetch only the reading bookmark"},"required":false,"description":"Whether to fetch only the reading bookmark"},{"in":"query","name":"key","schema":{"type":"integer","description":"Filter by key (surah/juz/page number)"},"required":false,"description":"Filter by key (surah/juz/page number)"},{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"},{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"required":false,"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"required":false,"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"required":false,"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"required":false,"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/BookmarkWithCollectionsCount"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":[{"id":"cmpwhmp9p0005lh28bxkkf80p","createdAt":"2023-01-21T07:28:13.023Z","type":"ayah","key":1,"verseNumber":5,"group":"verses_6236","isInDefaultCollection":true,"isReading":false,"collectionsCount":1}],"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1Bookmarks"}},"/v1/bookmarks/{bookmarkId}":{"delete":{"description":"Delete a standalone bookmark by id. This endpoint fully removes orphan bookmarks only. If the bookmark belongs to the virtual Favorites collection or any custom collection, it is not removed; this endpoint only sets `isReading` to `false` and leaves the bookmark attached to those collections. To remove it from Favorites or a custom collection, use the corresponding collection delete endpoint instead.","tags":["Bookmarks"],"summary":"Delete Bookmark","parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmpwhmpac0007lh28hpee43to"},"required":true,"description":"The id of the bookmark to be deleted."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["bookmark deleted"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"bookmark deleted"}}}},"headers":{"X-Mutation-At":{"description":"Unix timestamp (milliseconds) of the latest mutation for the user. Clients should store this value and include it in subsequent mutation requests for optimistic concurrency control.","schema":{"type":"string","example":"1731636500303"}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authDeleteV1BookmarksByBookmarkId"}},"/v1/bookmarks/ayahs-range":{"get":{"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"summary":"Get bookmarks within a range of Ayahs","parameters":[{"in":"query","name":"chapterNumber","schema":{"type":"integer","description":"The number of the Surah that the Ayahs range belong to."},"required":true,"description":"The number of the Surah that the Ayahs range belong to."},{"in":"query","name":"rangeStartAyahNumber","schema":{"type":"integer","description":"The Ayah number at which the range starts."},"required":true,"description":"The Ayah number at which the range starts."},{"in":"query","name":"rangeEndAyahNumber","schema":{"type":"integer","description":"The Ayah number at which the range ends."},"required":true,"description":"The Ayah number at which the range ends."},{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/RawBookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":[{"id":"cmpwhmp9q0006lh289ksz8c2m","createdAt":"2023-01-21T07:28:13.023Z","bookmarkType":"ayah","key":1,"verseNumber":5,"bookmarkGroup":"verses_6236","isInDefaultCollection":true,"isReading":false}],"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1BookmarksAyahsRange"}},"/v1/bookmarks/bookmark":{"get":{"description":"Get a bookmark by details","tags":["Bookmarks"],"summary":"Get bookmark","parameters":[{"in":"query","name":"isReading","schema":{"type":"boolean","description":"Whether to fetch the reading bookmark"},"description":"Whether to fetch the reading bookmark"},{"in":"query","name":"key","schema":{"type":"integer","oneOf":[{},{"x-required":true}],"description":"Surah, Juz or page number.","example":2},"description":"Surah, Juz or page number."},{"in":"query","name":"type","schema":{"type":"string","enum":["page","juz","surah","ayah"],"oneOf":[{},{"x-required":true}],"description":"The bookmark type.","default":"ayah"},"description":"The bookmark type."},{"in":"query","name":"verseNumber","schema":{"type":"integer","oneOf":[{},{"oneOf":[{"type":"number","format":"float","minimum":1,"x-required":true},{}]}],"description":"The Ayah number of the bookmark"},"description":"The Ayah number of the bookmark"},{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name.","example":4},"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Preferred field name."},{"in":"query","name":"mushaf","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`.","example":4},"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4 Legacy alias for `mushafId`."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Bookmark"}},"additionalProperties":false},"example":{"success":true,"data":{"id":"cmpwhmp9p0005lh28bxkkf80p","createdAt":"2023-01-21T07:28:13.023Z","type":"ayah","key":1,"verseNumber":5,"group":"verses_6236","isInDefaultCollection":true,"isReading":false,"collectionsCount":1}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1BookmarksBookmark"}},"/v1/bookmarks/collections":{"get":{"description":"Get named collection IDs for a bookmark by bookmark details. Pass `includeDefault=true` to also append `__default__` when the bookmark belongs to Favorites.","tags":["Bookmarks"],"summary":"Get bookmark collections","parameters":[{"in":"query","name":"key","schema":{"type":"number","format":"float","description":"Surah, Juz or page number."},"required":true,"description":"Surah, Juz or page number."},{"in":"query","name":"type","schema":{"type":"string","enum":["page","juz","surah","ayah"],"description":"The bookmark type.","default":"ayah"},"required":false,"description":"The bookmark type."},{"in":"query","name":"includeDefault","schema":{"type":"boolean","description":"When `true`, append `__default__` if the bookmark belongs to the virtual Favorites collection."},"required":false,"description":"When `true`, append `__default__` if the bookmark belongs to the virtual Favorites collection."},{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"},{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"required":false,"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"required":false,"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"required":false,"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"required":false,"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"string","description":"Collection ID. When `includeDefault=true`, this array may also include `__default__`.","example":"cmnkcpmvc000814v9f5jtbsxf"}}},"additionalProperties":false},"example":{"success":true,"data":["cmnkcpmvc000814v9f5jtbsxf"]}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1BookmarksCollections"}},"/v1/preferences":{"post":{"description":"Add or update one user preferences group like favorite Tafsirs or translations.","tags":["Preferences"],"summary":"Add or update preference","parameters":[{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"string","enum":["tafsirs","translations","audio","theme","quranReaderStyles","reading","language","userHasCustomised"],"description":"The preference group to be added or updated.","example":"tafsirs"},"key":{"type":"string","description":"The preference key to be added or updated.","example":"selectedTafsirs"},"value":{"description":"The preference value to be added or updated.","example":"[\"en-tafisr-ibn-kathir\"]"}},"required":["group","key","value"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"key":{"type":"string","enum":["type"]}},"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string","enum":["readingPreference","selectedWordByWordLocale","wordClickFunctionality","isReadingByRevelationOrder","wordByWordContentType","wordByWordDisplay","wordByWordTooltipContentType","wordByWordInlineContentType","selectedReadingTranslation","selectedReflectionLanguages","selectedLessonLanguages"]}},"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string","enum":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale","surahInfoFontScale","hadithFontScale","layersFontScale","quranFont","mushafLines","showTajweedRules"]}},"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string","enum":["selectedTranslations"]}},"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string","enum":["selectedTafsirs"]}},"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string","enum":["reciter","playbackRate","showTooltipWhenPlayingAudio","enableAutoScrolling","repeatSettings"]}},"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string","enum":["language"]}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","enum":["en","ar","bn","fa","fr","id","it","nl","pt","ru","sq","th","tr","ur","zh","ms","es","sw","vi"]}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","enum":["auto","light","sepia","dark"],"example":"auto"}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","enum":["translation","reading","readingTranslation"],"example":"translation"}},"required":["value"],"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","enum":["en","ur","id","bn","tr","fa","ru","hi","de","ta","inh","fr","sq","dv","zh","sd","ml"],"example":"en"}},"required":["value"],"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","enum":["play-audio","no-audio"],"example":"play-audio"}},"required":["value"],"additionalProperties":false},{"type":"object","properties":{"value":{"type":"boolean","example":true}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"array","items":{"type":"string","enum":["translation","transliteration"]},"example":["translation"]}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"array","items":{"type":"string","enum":["tooltip","inline"]},"example":["tooltip"]}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"array","items":{"type":"string","enum":["translation","transliteration"]},"example":[]}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","enum":["code_v1","code_v2","text_uthmani","text_indopak","qpc_uthmani_hafs","tajweed","tajweed_v4"],"example":"code_v1"}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","enum":["15_lines","16_lines"],"example":"16_lines"}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":10,"example":3}},"required":["value"],"additionalProperties":false},{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":6,"example":3}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"array","items":{"type":"integer","example":131}}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"array","items":{"type":"string","example":"en-tafisr-ibn-kathir"}}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"integer","enum":[0.25,0.5,0.75,1,1.25,1.5,1.75,2],"example":1}},"additionalProperties":false},{"type":"object","properties":{"value":{"type":"boolean","example":false}},"required":["value"],"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string","enum":["userHasCustomised"]}},"required":["key"],"additionalProperties":false},{"type":"object","properties":{"value":{"type":"string","minLength":1,"maxLength":255,"example":"131"}},"required":["value"],"additionalProperties":false},{"type":"object","properties":{"value":{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}},"required":["value"],"additionalProperties":false}]},"example":{"key":"type"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["preference updated"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"preference updated"}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1Preferences"},"get":{"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"summary":"Get user preferences","parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/Preference"}},"additionalProperties":false},"example":{"success":true,"data":{"theme":{"type":"auto"},"reading":{"readingPreference":"translation","selectedWordByWordLocale":"en","wordClickFunctionality":"play-audio","isReadingByRevelationOrder":true,"wordByWordContentType":["translation"],"wordByWordDisplay":["tooltip"],"wordByWordTooltipContentType":["translation"],"wordByWordInlineContentType":[],"selectedReadingTranslation":"131","selectedReflectionLanguages":["string"],"selectedLessonLanguages":["string"]},"quranReaderStyles":{"tafsirFontScale":3,"quranTextFontScale":3,"translationFontScale":3,"wordByWordFontScale":3,"reflectionFontScale":3,"qnaFontScale":3,"lessonFontScale":3,"surahInfoFontScale":3,"hadithFontScale":3,"layersFontScale":3,"quranFont":"code_v1","mushafLines":"16_lines","showTajweedRules":true},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"},"userHasCustomised":{"userHasCustomised":false}}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1Preferences"}},"/v1/preferences/bulk":{"post":{"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["Preferences"],"summary":"Bulk add or update preferences","parameters":[{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preference"},"example":{"theme":{"type":"auto"},"reading":{"readingPreference":"translation","selectedWordByWordLocale":"en","wordClickFunctionality":"play-audio","isReadingByRevelationOrder":true,"wordByWordContentType":["translation"],"wordByWordDisplay":["tooltip"],"wordByWordTooltipContentType":["translation"],"wordByWordInlineContentType":[],"selectedReadingTranslation":"131","selectedReflectionLanguages":["string"],"selectedLessonLanguages":["string"]},"quranReaderStyles":{"tafsirFontScale":3,"quranTextFontScale":3,"translationFontScale":3,"wordByWordFontScale":3,"reflectionFontScale":3,"qnaFontScale":3,"lessonFontScale":3,"surahInfoFontScale":3,"hadithFontScale":3,"layersFontScale":3,"quranFont":"code_v1","mushafLines":"16_lines","showTajweedRules":true},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"},"userHasCustomised":{"userHasCustomised":false}}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["preferences updated"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"preferences updated"}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1PreferencesBulk"}},"/v1/reading-sessions":{"post":{"description":"Track the user's most recent reading location (Surah/Ayah) for \"Continue reading\" / \"Recently read\" UX. This endpoint stores location only; it does not credit reading time, streaks, goals, or activity-calendar progress.\n\nA new reading session will be created if the user does not have an existing one in the past 20 minutes; otherwise, the existing reading session will be updated with the latest read Ayah.\n\nCall this when the latest visible/read Ayah changes. Quran.com debounces this call so frequent scrolling updates the user's resume location without sending one request for every intersection event.\n\nFor streaks, goals, and calendar-style progress tracking, call `POST /v1/activity-days` with the read ranges, active reading seconds, and Mushaf id. See [Reading Sessions vs Activity Days](/docs/user-related-apis/reading-sessions-vs-activity-days).","tags":["Reading Sessions"],"summary":"Add or update user reading session","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chapterNumber":{"type":"integer","minimum":1,"description":"The Surah number of the latest visible/read Ayah. Used for resume and recently-read UX.","example":1},"verseNumber":{"type":"integer","minimum":1,"description":"The Ayah number within chapterNumber for the latest visible/read Ayah.","example":1},"clientCreatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was created. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:15:30.000Z"},"clientUpdatedAt":{"oneOf":[{"type":"string","format":"date-time"}],"description":"Client-local timestamp when this resource was last updated. Accepts ISO 8601 date strings or JavaScript Unix timestamps in milliseconds.","example":"2026-05-19T10:16:30.000Z"}},"required":["chapterNumber","verseNumber"],"additionalProperties":false},"example":{"chapterNumber":1,"verseNumber":1,"clientCreatedAt":"2026-05-19T10:15:30.000Z","clientUpdatedAt":"2026-05-19T10:16:30.000Z"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"type":"string","enum":["reading session created","reading session updated"],"example":"reading session created"}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"reading session created"}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1ReadingSessions"},"get":{"description":"Get the user's reading sessions, ordered most recent first. Reading sessions are location history for \"Continue reading\" and \"Recently read\" UX. They do not represent daily progress totals; for streaks, goals, and calendar-style progress, use Activity Days.","tags":["Reading Sessions"],"summary":"Get user reading sessions","parameters":[{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":[{"id":"cmpwhmqau000klh285fxud33f","updatedAt":"2023-01-21T07:28:13.023Z","chapterNumber":1,"verseNumber":5}],"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1ReadingSessions"}},"/v1/goals/get-todays-plan":{"get":{"description":"Get today's goal plan. When a goal exists, `goalId` is the reading goal id to use with update/delete goal endpoints, while `id` is the activity day id.","tags":["Goals"],"summary":"Get today's goal plan","parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type of the goal."},{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"},{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmpwhmowr0004lh285hzp2ufu"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-30"},"progress":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"The progress of the reading goal of that activity day (if the user has a reading goal on that day).","example":0.695},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The activity category. Use QURAN for Quran reading progress; other values are for lessons and Quran reading programs.","example":"QURAN"},"ranges":{"oneOf":[{"type":"array","items":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"}}],"description":"The ranges read on that day (will be included only when the type is QURAN)","example":["1:1-1:2"]},"pagesRead":{"oneOf":[{"type":"number","format":"float"}],"description":"The number of pages read on that day (will be included only when the type is QURAN)","example":1.637041020126048},"secondsRead":{"oneOf":[{"type":"integer"}],"description":"The number of seconds spent reading on that day (will be included only when the type is QURAN)","example":417},"versesRead":{"oneOf":[{"type":"integer"}],"description":"The number of Ayahs read on that day (will be included only when the type is QURAN)","example":24},"manuallyAddedSeconds":{"oneOf":[{"type":"integer"}],"description":"The number of seconds spent reading that was manually input by the user and not auto-tracked (will be included only when the type is QURAN)","example":24},"dailyTargetPages":{"oneOf":[{"type":"number","format":"float"}],"description":"The number of pages user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":1.637041020126048},"dailyTargetSeconds":{"oneOf":[{"type":"integer"}],"description":"The number of seconds user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":5},"dailyTargetRanges":{"oneOf":[{"type":"array","items":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"}}],"description":"The range of Ayahs user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":["1:1-1:2"]},"remainingDailyTargetRanges":{"oneOf":[{"type":"array","items":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"}}],"description":"The remaining range of Ayahs user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":["1:1-1:2"]},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"hasGoal":{"type":"boolean","description":"Whether the user has a goal.","example":true},"goalId":{"type":"string","description":"The id of the reading goal. Present when `hasGoal` is true. Use this id with PUT /v1/goals/{id} and DELETE /v1/goals/{id}.","example":"cmpwhmpy8000hlh289ihcgauj"}},"required":["hasGoal"],"additionalProperties":false,"description":"The Mushaf used to read on that day (will be included only when the type is QURAN) \n\nThe id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":{"hasGoal":true,"goalId":"cmpwhmpy9000ilh2869bq8w0w","id":"cmpwhmpy9000jlh28649u6vqa","date":"2023-09-30","progress":0.695,"type":"QURAN","ranges":["1:1-1:2"],"pagesRead":1.637041020126048,"secondsRead":417,"versesRead":24,"manuallyAddedSeconds":24,"dailyTargetPages":1.637041020126048,"dailyTargetSeconds":5,"dailyTargetRanges":["1:1-1:2"],"remainingDailyTargetRanges":["1:1-1:2"],"mushafId":4}}},"additionalProperties":false},"example":{"success":true,"data":{"hasGoal":true,"goalId":"cmpwhmpy9000ilh2869bq8w0w","id":"cmpwhmpy9000jlh28649u6vqa","date":"2023-09-30","progress":0.695,"type":"QURAN","ranges":["1:1-1:2"],"pagesRead":1.637041020126048,"secondsRead":417,"versesRead":24,"manuallyAddedSeconds":24,"dailyTargetPages":1.637041020126048,"dailyTargetSeconds":5,"dailyTargetRanges":["1:1-1:2"],"remainingDailyTargetRanges":["1:1-1:2"],"mushafId":4}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1GoalsGetTodaysPlan"}},"/v1/goals/{id}":{"put":{"description":"Update a goal","tags":["Goals"],"summary":"Update a goal","parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmpwhmpsu000glh28gr68dkhe"},"required":true,"description":"The id of the goal."},{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"},{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM","RAMADAN_CHALLENGE"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:7","x-required":true},{"type":"integer","minimum":1,"example":600,"x-required":true}],"description":"The amount of the goal. Depending on the goal type, the amount value and format will be different"},"duration":{"type":"integer","minimum":1,"description":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based."},"category":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM","RAMADAN_CHALLENGE"],"description":"The category of the goal"}},"additionalProperties":false,"example":{"type":"QURAN_TIME","amount":600,"duration":1,"category":"QURAN"}},"example":{"type":"QURAN_TIME","amount":600,"duration":1,"category":"QURAN"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPutV1GoalsById"},"delete":{"description":"Delete a goal by id.","tags":["Goals"],"summary":"Delete a goal","parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmpwhmpsu000glh28gr68dkhe"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM","RAMADAN_CHALLENGE"],"description":"The category of the goal"},"required":true,"description":"The category of the goal"},{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"message":{"enum":["goal deleted"]}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"message":"goal deleted"}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authDeleteV1GoalsById"}},"/v1/goals":{"post":{"description":"Create a goal","tags":["Goals"],"summary":"Create a goal","parameters":[{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"},{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM","RAMADAN_CHALLENGE"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:7","x-required":true},{"type":"integer","minimum":1,"example":600,"x-required":true}],"description":"The amount of the goal. Depending on the goal type, the amount value and format will be different"},"duration":{"type":"integer","minimum":1,"description":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based."},"category":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM","RAMADAN_CHALLENGE"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":false,"example":{"type":"QURAN_TIME","amount":600,"duration":1,"category":"QURAN"}},"example":{"type":"QURAN_TIME","amount":600,"duration":1,"category":"QURAN"}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"id":{"type":"string","description":"The id of the goal.","example":"cmpwhmpsu000glh28gr68dkhe"}},"required":["id"],"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"id":"cmpwhmpsu000glh28gr68dkhe"}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authPostV1Goals"}},"/v1/goals/estimate":{"get":{"description":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","tags":["Goals"],"summary":"Generate timeline estimation","parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM","RAMADAN_CHALLENGE"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type of the goal."},{"in":"query","name":"amount","schema":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:7","x-required":true},{"type":"integer","minimum":1,"example":600,"x-required":true}],"description":"The amount of the goal. Depending on the goal type, the amount value and format will be different"},"required":true,"description":"The amount of the goal. Depending on the goal type, the amount value and format will be different"},{"in":"query","name":"duration","schema":{"type":"integer","minimum":1,"description":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based."},"required":false,"description":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based."},{"in":"query","name":"mushafId","schema":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4},"required":true,"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"},{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"$ref":"#/components/schemas/EstimatedGoalTimeline"}},"additionalProperties":false},"example":{"success":true,"data":{"week":[{"date":"2023-01-21T07:28:13.023Z","amount":"1:5-1:7"}]}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1GoalsEstimate"}},"/v1/streaks":{"get":{"description":"Get user streaks.","tags":["Streaks"],"summary":"Get streaks","parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date after which any streaks would be returned (inclusive)","example":"2023-09-01"},"description":"The date after which any streaks would be returned (inclusive)"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date before which any streaks would be returned (inclusive)","example":"2023-09-30"},"description":"The date before which any streaks would be returned (inclusive)"},{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN"],"description":"The type of the streak","example":"QURAN"},"description":"The type of the streak"},{"in":"query","name":"sortOrder","schema":{"type":"string","enum":["asc","desc"],"description":"The sorting order of `orderBy` field","example":"desc","default":"desc"},"description":"The sorting order of `orderBy` field"},{"in":"query","name":"orderBy","schema":{"type":"string","enum":["startDate","days"],"description":"Which field to order the streaks by","example":"startDate","default":"startDate"},"description":"Which field to order the streaks by"},{"in":"query","name":"status","schema":{"type":"string","enum":["ACTIVE","BROKEN"],"description":"The status of the streak.","example":"ACTIVE"},"description":"The status of the streak."},{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"},{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The id of the streak.","example":"cmpwhmqbn000llh289f60a1x9"},"startDate":{"type":"string","format":"date-time","description":"The start timestamp of the streak.","example":"2023-09-01T00:00:00.000Z"},"endDate":{"type":"string","format":"date-time","description":"The end timestamp of the streak.","example":"2023-09-30T23:59:59.999Z"},"type":{"type":"string","enum":["QURAN"],"description":"The type of the streak.","example":"QURAN"},"status":{"type":"string","enum":["ACTIVE","BROKEN"],"description":"The status of the streak.","example":"ACTIVE"},"days":{"type":"integer","description":"The number of days the streak is/was active for.","example":5}},"required":["id","startDate","endDate","type","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":[{"id":"cmpwhmqbn000llh289f60a1x9","startDate":"2023-09-01T00:00:00.000Z","endDate":"2023-09-30T23:59:59.999Z","type":"QURAN","status":"ACTIVE","days":5}],"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1Streaks"}},"/v1/streaks/current-streak-days":{"get":{"description":"Get current active streak days.","tags":["Streaks"],"summary":"Get current streak days","parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN"],"description":"The type of the streak","example":"QURAN"},"required":true,"description":"The type of the streak"},{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"days":{"type":"integer","description":"The number of days the current streak is active for.","example":5}},"required":["days"],"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"days":5}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1StreaksCurrentStreakDays"}},"/v1/activity-days":{"post":{"description":"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.\n\nThis 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.\n\nFor `type=QURAN`, send:\n- `type`: use `QURAN` when the activity is Quran reading progress.\n- `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.\n- `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.\n- `mushafId`: the Mushaf layout/font the user is reading with. This lets the backend calculate page-based progress consistently with the client.\n- `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.\n\nA robust client implementation can follow this pattern, adapted from Quran.com's reader flow.\n1. When a verse becomes visible, queue its verse key and debounce a `POST /v1/reading-sessions` call for the latest location.\n2. Track active reading seconds while the browser tab is focused.\n3. Every few seconds, merge the queued verse keys into ranges and call `POST /v1/activity-days` with `type`, `seconds`, `ranges`, and `mushafId`.\n4. Keep in-flight queue entries recoverable until the activity-days request succeeds. If it fails, requeue them for retry and keep the buffered seconds.","tags":["Activity Days"],"summary":"Add/update activity day","parameters":[{"in":"header","name":"x-timezone","schema":{"type":"string","description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","example":"Asia/Saigon"},"description":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"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.","example":"2023-09-01"},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The activity category. Use QURAN for Quran reading progress; other values are for lessons and Quran reading programs.","example":"QURAN"}},"required":["type"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"seconds":{"type":"integer","minimum":1,"description":"Active reading time, in seconds, to credit for this sync batch of ranges.","example":5},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"},"description":"Inclusive Ayah ranges read in this sync batch, formatted as chapter:verse-chapter:verse.","example":["1:5-1:7"]},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4}},"required":["seconds","ranges","mushafId"],"additionalProperties":false,"title":"QURAN"}],"example":{"date":"2023-09-01","type":"QURAN","seconds":5,"ranges":["1:5-1:7"],"mushafId":4}},"example":{"date":"2023-09-01","type":"QURAN","seconds":5,"ranges":["1:5-1:7"],"mushafId":4}}}},"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object"}},"additionalProperties":false},"example":{"success":true,"data":{}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"x-code-samples":[{"lang":"javascript","label":"Recommended reading sync pattern","source":"const READ_PROGRESS_SYNC_MS = 5000;\nconst READING_SESSION_DEBOUNCE_MS = 2000;\n\nconst observedVerseKeys = new Set();\nlet elapsedReadingTimeInSeconds = 0;\nlet isSyncingReadingProgress = false;\nlet readingTimer = null;\n\nfunction onVerseVisible(verseKey) {\n observedVerseKeys.add(verseKey);\n\n const [chapterNumber, verseNumber] = verseKey.split(':').map(Number);\n debouncedPostReadingSession({ chapterNumber, verseNumber });\n}\n\nconst debouncedPostReadingSession = debounce(({ chapterNumber, verseNumber }) => {\n post('/v1/reading-sessions', { chapterNumber, verseNumber });\n}, READING_SESSION_DEBOUNCE_MS);\n\nsetInterval(async () => {\n if (\n isSyncingReadingProgress ||\n observedVerseKeys.size === 0 ||\n elapsedReadingTimeInSeconds === 0\n ) {\n return;\n }\n\n isSyncingReadingProgress = true;\n\n let verseKeysToSync = [];\n try {\n verseKeysToSync = Array.from(observedVerseKeys);\n verseKeysToSync.forEach((verseKey) => observedVerseKeys.delete(verseKey));\n\n const ranges = mergeVerseKeys(verseKeysToSync);\n const seconds = elapsedReadingTimeInSeconds;\n\n await post('/v1/activity-days', {\n type: 'QURAN',\n seconds,\n ranges,\n mushafId: 4,\n });\n\n elapsedReadingTimeInSeconds = Math.max(0, elapsedReadingTimeInSeconds - seconds);\n } catch (error) {\n verseKeysToSync.forEach((verseKey) => observedVerseKeys.add(verseKey));\n // Keep buffered progress so the next sync can retry.\n } finally {\n isSyncingReadingProgress = false;\n }\n}, READ_PROGRESS_SYNC_MS);\n\nfunction startReadingTimer() {\n if (readingTimer) return;\n\n readingTimer = setInterval(() => {\n elapsedReadingTimeInSeconds += 1;\n }, 1000);\n}\n\nfunction stopReadingTimer() {\n clearInterval(readingTimer);\n readingTimer = null;\n}\n\nwindow.addEventListener('focus', startReadingTimer);\nwindow.addEventListener('blur', stopReadingTimer);\nstartReadingTimer();"}],"operationId":"authPostV1ActivityDays"},"get":{"description":"Get the user's activity days for calendar/history views. Activity Days contain daily progress totals such as read ranges, pages, seconds, and goal progress for each date and activity type. Use `from`/`to` to filter by date range and `type` to filter by activity type.","tags":["Activity Days"],"summary":"Get activity days","parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Start date, inclusive, for the activity-day history window.","example":"2023-09-01"},"description":"Start date, inclusive, for the activity-day history window."},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"End date, inclusive, for the activity-day history window.","example":"2023-09-30"},"description":"End date, inclusive, for the activity-day history window."},{"in":"query","name":"dateOrderBy","schema":{"type":"string","enum":["asc","desc"],"description":"Order by activity day's date","example":"desc","default":"desc"},"description":"Order by activity day's date"},{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The activity category. Use QURAN for Quran reading progress; other values are for lessons and Quran reading programs.","example":"QURAN"},"description":"The activity category. Use QURAN for Quran reading progress; other values are for lessons and Quran reading programs."},{"in":"query","name":"last","schema":{"type":"integer","minimum":1,"maximum":20,"description":"The number of items to be fetched. Should be used together with `before`","example":10},"description":"The number of items to be fetched. Should be used together with `before`"},{"in":"query","name":"first","schema":{"type":"integer","minimum":1,"maximum":20,"oneOf":[{"type":"integer"}],"description":"The number of items to be fetched.","example":10},"description":"The number of items to be fetched."},{"in":"query","name":"after","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor after which you want to get the next page of items. Should be used together with `first`","example":"cmpwhmovp0000lh2878ux8voa"},"description":"The cursor after which you want to get the next page of items. Should be used together with `first`"},{"in":"query","name":"before","schema":{"type":"string","oneOf":[{"type":"string"}],"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","example":"cmpwhmovq0001lh282cltdjkf"},"description":"The cursor before which the previous page of items will be fetched. Should be used together with `last`"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmpwhmowr0004lh285hzp2ufu"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-30"},"progress":{"type":"number","format":"float","minimum":0,"maximum":1,"description":"The progress of the reading goal of that activity day (if the user has a reading goal on that day).","example":0.695},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The activity category. Use QURAN for Quran reading progress; other values are for lessons and Quran reading programs.","example":"QURAN"},"ranges":{"oneOf":[{"type":"array","items":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"}}],"description":"The ranges read on that day (will be included only when the type is QURAN)","example":["1:1-1:2"]},"pagesRead":{"oneOf":[{"type":"number","format":"float"}],"description":"The number of pages read on that day (will be included only when the type is QURAN)","example":1.637041020126048},"secondsRead":{"oneOf":[{"type":"integer"}],"description":"The number of seconds spent reading on that day (will be included only when the type is QURAN)","example":417},"versesRead":{"oneOf":[{"type":"integer"}],"description":"The number of Ayahs read on that day (will be included only when the type is QURAN)","example":24},"manuallyAddedSeconds":{"oneOf":[{"type":"integer"}],"description":"The number of seconds spent reading that was manually input by the user and not auto-tracked (will be included only when the type is QURAN)","example":24},"dailyTargetPages":{"oneOf":[{"type":"number","format":"float"}],"description":"The number of pages user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":1.637041020126048},"dailyTargetSeconds":{"oneOf":[{"type":"integer"}],"description":"The number of seconds user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":5},"dailyTargetRanges":{"oneOf":[{"type":"array","items":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"}}],"description":"The range of Ayahs user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":["1:1-1:2"]},"remainingDailyTargetRanges":{"oneOf":[{"type":"array","items":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"}}],"description":"The remaining range of Ayahs user should read on that day to meet their goal's target if a goal was set (will be included only when the type is QURAN)","example":["1:1-1:2"]},"mushafId":{"type":"integer","enum":[1,2,3,4,5,6,7,11,19],"description":"The id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4","example":4}},"required":["id","date","progress","type","mushafId"],"additionalProperties":false,"description":"The Mushaf used to read on that day (will be included only when the type is QURAN) \n\nThe id of the Mushaf being used. \n\n1 = QCFV2 \n\n 2 = QCFV1 \n\n 3 = Indopak \n\n 4 = UthmaniHafs \n\n 5 = KFGQPCHAFS \n\n 6 = Indopak15Lines \n\n 7 = Indopak16Lines \n\n 11 = Tajweeed \n\n 19 = QCFTajweedV4"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmpwhmovq0002lh28dhdegr5q"},"endCursor":{"type":"string","example":"cmpwhmovq0003lh289lbvh5yp"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":[{"id":"cmpwhmowr0004lh285hzp2ufu","date":"2023-09-30","progress":0.695,"type":"QURAN","ranges":["1:1-1:2"],"pagesRead":1.637041020126048,"secondsRead":417,"versesRead":24,"manuallyAddedSeconds":24,"dailyTargetPages":1.637041020126048,"dailyTargetSeconds":5,"dailyTargetRanges":["1:1-1:2"],"remainingDailyTargetRanges":["1:1-1:2"],"mushafId":4}],"pagination":{"startCursor":"cmpwhmovq0002lh28dhdegr5q","endCursor":"cmpwhmovq0003lh289lbvh5yp","hasNextPage":true,"hasPreviousPage":false}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1ActivityDays"}},"/v1/activity-days/estimate-reading-time":{"get":{"description":"Estimate how many seconds it would take to read one or more verse ranges. This is useful when a client has ranges but needs a reasonable seconds value for manual/backfilled Quran activity. The estimate is based on average reading speed observed on Quran.com.","tags":["Activity Days"],"summary":"Estimate reading time","parameters":[{"in":"query","name":"ranges","schema":{"type":"string","pattern":"^(\\d+:\\d+-\\d+:\\d+(?:,\\d+:\\d+-\\d+:\\d+)*)$","description":"a comma separated string of Ayah ranges e.g. 1:1-1:2","example":"1:1-1:2"},"required":true,"description":"a comma separated string of Ayah ranges e.g. 1:1-1:2"}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"seconds":{"type":"integer","description":"The number of seconds it would take on average to read the range of Ayahs.","example":66.8}},"required":["seconds"],"additionalProperties":false}},"additionalProperties":false},"example":{"success":true,"data":{"seconds":66.8}}}}},"400":{"description":"The request is missing required parameters or is invalid.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request is missing required headers or is invalid"},"type":{"type":"string","example":"invalid_request"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"401":{"description":"The request is unauthorized.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request requires user authentication"},"type":{"type":"string","example":"unauthorized"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"403":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server understood the request, but refuses to authorize it"},"type":{"type":"string","example":"forbidden"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"404":{"description":"Not Found. The resource being accessed does not exist.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The requested resource could not be found"},"type":{"type":"string","example":"not_found"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"422":{"description":"Validation Error. The request includes one or more invalid params. Please check the request params and try again.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request was well-formed but was unable to be followed due to semantic errors"},"type":{"type":"string","example":"unprocessable_entity"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"429":{"description":"Too many requests, please try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Too many requests, please try again later"},"type":{"type":"string","example":"rate_limit_exceeded"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"500":{"description":"Server Error. Something went wrong, try again later.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server encountered an internal error and was unable to complete your request"},"type":{"type":"string","example":"internal_server_error"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"502":{"description":"Invalid response from the upstream server","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and received an invalid response from the upstream server"},"type":{"type":"string","example":"bad_gateway"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"503":{"description":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server is currently unable to handle the request due to a temporary overload or scheduled maintenance"},"type":{"type":"string","example":"service_unavailable"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}},"504":{"description":"The server did not receive a timely response from the upstream server.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The server was acting as a gateway or proxy and did not receive a timely response from the upstream server"},"type":{"type":"string","example":"gateway_timeout"},"success":{"type":"boolean","example":false}},"additionalProperties":false}}}}},"operationId":"authGetV1ActivityDaysEstimateReadingTime"}},"/v1/users/profile":{"patch":{"operationId":"UsersController_editProfile","summary":"Edit user profile","description":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","parameters":[],"requestBody":{"requ | |||
There was a problem hiding this comment.
For the pre-live /v1/collections/{collectionId} 200 response, both newly added collection examples omit data.collection.modifiable, but #/components/schemas/Collection in this same spec marks modifiable as required. Any docs tooling or contract tests that validate examples against the schema will now reject these examples for the pre-live collection endpoint.
Useful? React with 👍 / 👎.
Deploying qf-api-docs with
|
| Latest commit: |
87f11de
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://77b9ba1b.qf-api-docs.pages.dev |
| Branch Preview URL: | https://codex-user-response-examples.qf-api-docs.pages.dev |
Collaborator
Author
|
Closing because the source of truth for User API v1 OpenAPI output is quran/quran.com-users-backend. I will move these response examples into that backend repo instead. |
Collaborator
Author
|
Replacement source-of-truth PR is now open in the users backend repo: https://github.com/quran/quran.com-users-backend/pull/1241 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Split out from PR #167 so User API examples can be reviewed independently.
Scope:
openAPI/user-related-apis/v1.jsonandopenAPI/user-related-apis/pre-live/v1.json.Note:
Local validation:
git diff --checkHosted validation: