From 30285f5b79f30c587241bea48b54790642305f9a Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Sun, 25 Jan 2026 15:43:44 +0700 Subject: [PATCH 1/9] add sync docs --- .../1.0.0/revoke-oidc-session.api.mdx | 11 +- .../revoke-oidc-session.api.mdx | 11 +- .../1.0.0/search-controller-search.api.mdx | 6 +- .../search-controller-search.api.mdx | 6 +- .../1.0.0/add-collection-bookmark.api.mdx | 10 +- .../1.0.0/add-collection.api.mdx | 10 +- .../1.0.0/add-note.api.mdx | 10 +- .../1.0.0/add-or-update-preference.api.mdx | 4 +- ...add-or-update-user-reading-session.api.mdx | 2 +- .../1.0.0/add-update-activity-day.api.mdx | 2 +- .../1.0.0/add-user-bookmark.api.mdx | 10 +- .../bulk-add-or-update-preferences.api.mdx | 4 +- .../1.0.0/comments-controller-create.api.mdx | 2 +- .../1.0.0/comments-controller-get.api.mdx | 2 +- .../1.0.0/create-a-goal.api.mdx | 4 +- .../1.0.0/delete-a-goal.api.mdx | 4 +- .../1.0.0/delete-bookmark.api.mdx | 10 +- .../delete-collection-bookmark-by-id.api.mdx | 10 +- .../1.0.0/delete-collection.api.mdx | 10 +- .../1.0.0/delete-note-by-id.api.mdx | 10 +- .../1.0.0/get-activity-days.api.mdx | 8 +- .../1.0.0/get-all-collection-items.api.mdx | 6 +- .../1.0.0/get-all-collections.api.mdx | 6 +- .../1.0.0/get-all-notes.api.mdx | 4 +- .../1.0.0/get-bookmark-collections.api.mdx | 6 +- .../1.0.0/get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../1.0.0/get-collection-items-by-id.api.mdx | 6 +- .../1.0.0/get-mutations.api.mdx | 86 + .../1.0.0/get-notes-by-verse.api.mdx | 4 +- .../1.0.0/get-streaks.api.mdx | 6 +- .../1.0.0/get-todays-goal-plan.api.mdx | 4 +- .../1.0.0/get-user-bookmarks.api.mdx | 6 +- .../1.0.0/get-user-preferences.api.mdx | 4 +- .../1.0.0/get-user-reading-sessions.api.mdx | 6 +- .../1.0.0/posts-controller-create.api.mdx | 4 +- .../1.0.0/posts-controller-edit.api.mdx | 4 +- .../1.0.0/posts-controller-feed.api.mdx | 2 +- .../1.0.0/posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../1.0.0/publish-note.api.mdx | 10 +- .../1.0.0/sidebar.js | 2 +- .../1.0.0/sync-local-mutations.api.mdx | 94 + .../1.0.0/tags-controller-find.api.mdx | 2 +- .../1.0.0/update-a-goal.api.mdx | 4 +- .../1.0.0/update-collection.api.mdx | 10 +- .../1.0.0/update-note-by-id.api.mdx | 10 +- .../add-collection-bookmark.api.mdx | 10 +- .../add-collection.api.mdx | 10 +- .../add-note.api.mdx | 10 +- .../add-or-update-preference.api.mdx | 4 +- ...add-or-update-user-reading-session.api.mdx | 2 +- .../add-update-activity-day.api.mdx | 2 +- .../add-user-bookmark.api.mdx | 10 +- .../bulk-add-or-update-preferences.api.mdx | 4 +- .../comments-controller-create.api.mdx | 2 +- .../comments-controller-get.api.mdx | 2 +- .../create-a-goal.api.mdx | 4 +- .../delete-a-goal.api.mdx | 4 +- .../delete-bookmark.api.mdx | 10 +- .../delete-collection-bookmark-by-id.api.mdx | 10 +- .../delete-collection.api.mdx | 10 +- .../delete-note-by-id.api.mdx | 10 +- .../get-activity-days.api.mdx | 8 +- .../get-all-collection-items.api.mdx | 6 +- .../get-all-collections.api.mdx | 6 +- .../get-all-notes.api.mdx | 4 +- .../get-bookmark-collections.api.mdx | 6 +- .../get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../get-collection-items-by-id.api.mdx | 6 +- .../get-mutations.api.mdx | 86 + .../get-notes-by-verse.api.mdx | 4 +- .../get-streaks.api.mdx | 6 +- .../get-todays-goal-plan.api.mdx | 4 +- .../get-user-bookmarks.api.mdx | 6 +- .../get-user-preferences.api.mdx | 4 +- .../get-user-reading-sessions.api.mdx | 6 +- .../posts-controller-create.api.mdx | 4 +- .../posts-controller-edit.api.mdx | 4 +- .../posts-controller-feed.api.mdx | 2 +- .../posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../publish-note.api.mdx | 10 +- docs/user_related_apis_versioned/sidebar.js | 2 +- .../sync-local-mutations.api.mdx | 94 + .../tags-controller-find.api.mdx | 2 +- .../update-a-goal.api.mdx | 4 +- .../update-collection.api.mdx | 10 +- .../update-note-by-id.api.mdx | 10 +- openAPI/user-related-apis/v1.json | 17133 +++++++++++++++- 99 files changed, 17792 insertions(+), 211 deletions(-) create mode 100644 docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx create mode 100644 docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx create mode 100644 docs/user_related_apis_versioned/get-mutations.api.mdx create mode 100644 docs/user_related_apis_versioned/sync-local-mutations.api.mdx diff --git a/docs/oauth2_apis_versioned/1.0.0/revoke-oidc-session.api.mdx b/docs/oauth2_apis_versioned/1.0.0/revoke-oidc-session.api.mdx index 4b3c1ede..aa24dcc7 100644 --- a/docs/oauth2_apis_versioned/1.0.0/revoke-oidc-session.api.mdx +++ b/docs/oauth2_apis_versioned/1.0.0/revoke-oidc-session.api.mdx @@ -5,7 +5,7 @@ description: "This endpoint handles the user logout process in Quran.Foundation' sidebar_label: "OpenID Connect Logout" hide_title: true hide_table_of_contents: true -api: {"description":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nThe logout process follows the OpenID Connect specifications:\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","operationId":"revokeOidcSession","responses":{"302":{"description":"Successful logout. The user will be redirected to complete the logout process."}},"tags":["OIDC"],"method":"get","path":"/oauth2/sessions/logout","servers":[{"url":"https://oauth2.quran.foundation","description":"Production Server"},{"url":"https://staging-oauth2.quran.foundation","description":"Staging Server"}],"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"},"basicAuth":{"type":"http","scheme":"basic","description":"Basic authentication for client credentials"}},"info":{"title":"OAuth2 APIs","version":"1.0.0","description":"Quran.Foundation OAuth2 APIs are a set of APIs that allow you to integrate your app with Quran.Foundation's OAuth2 capabilities. This includes endpoints for OpenID Connect Userinfo, OAuth2 Token Exchange, and OAuth2 Authorize. The APIs are designed to be simple and easy to use, with a focus on security and privacy. Integrating with Quran.Foundation's OAuth2 APIs is required to access Quran.Foundation's APIs."},"postman":{"name":"OpenID Connect Logout","description":{"content":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nThe logout process follows the OpenID Connect specifications:\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","type":"text/plain"},"url":{"path":["oauth2","sessions","logout"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"method":"GET"}} +api: {"description":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nTo redirect users back to your app after logout, include `post_logout_redirect_uri`. The redirect URI must be pre-registered in your OAuth2 client configuration.\n\nThe logout process follows the OpenID Connect specifications:\n- [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","operationId":"revokeOidcSession","parameters":[{"in":"query","name":"id_token_hint","description":"The ID token received during authentication. Optional but recommended for identifying the user session.","required":false,"schema":{"type":"string","example":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}},{"in":"query","name":"post_logout_redirect_uri","description":"Where to redirect the user after logout. Must be pre-registered in your OAuth2 client's `post_logout_redirect_uris`.","required":false,"schema":{"type":"string","example":"https://your-app.com/"}},{"in":"query","name":"state","description":"Opaque value passed back to the `post_logout_redirect_uri` for CSRF protection.","required":false,"schema":{"type":"string","example":"af0ifjsldkj"}}],"responses":{"302":{"description":"Successful logout. The user will be redirected to complete the logout process."}},"tags":["OIDC"],"method":"get","path":"/oauth2/sessions/logout","servers":[{"url":"https://oauth2.quran.foundation","description":"Production Server"},{"url":"https://staging-oauth2.quran.foundation","description":"Staging Server"}],"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"},"basicAuth":{"type":"http","scheme":"basic","description":"Basic authentication for client credentials"}},"info":{"title":"OAuth2 APIs","version":"1.0.0","description":"Quran.Foundation OAuth2 APIs are a set of APIs that allow you to integrate your app with Quran.Foundation's OAuth2 capabilities. This includes endpoints for OpenID Connect Userinfo, OAuth2 Token Exchange, and OAuth2 Authorize. The APIs are designed to be simple and easy to use, with a focus on security and privacy. Integrating with Quran.Foundation's OAuth2 APIs is required to access Quran.Foundation's APIs."},"postman":{"name":"OpenID Connect Logout","description":{"content":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nTo redirect users back to your app after logout, include `post_logout_redirect_uri`. The redirect URI must be pre-registered in your OAuth2 client configuration.\n\nThe logout process follows the OpenID Connect specifications:\n- [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","type":"text/plain"},"url":{"path":["oauth2","sessions","logout"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The ID token received during authentication. Optional but recommended for identifying the user session.","type":"text/plain"},"key":"id_token_hint","value":""},{"disabled":false,"description":{"content":"Where to redirect the user after logout. Must be pre-registered in your OAuth2 client's `post_logout_redirect_uris`.","type":"text/plain"},"key":"post_logout_redirect_uri","value":""},{"disabled":false,"description":{"content":"Opaque value passed back to the `post_logout_redirect_uri` for CSRF protection.","type":"text/plain"},"key":"state","value":""}],"variable":[]},"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/oauth2_apis_versioned/1.0.0/oauth-2-apis custom_edit_url: null @@ -29,15 +29,16 @@ This endpoint handles the user logout process in Quran.Foundation's OAuth2 & Ope 1. Ends the user's current session 2. Revokes associated access and refresh tokens +To redirect users back to your app after logout, include `post_logout_redirect_uri`. The redirect URI must be pre-registered in your OAuth2 client configuration. + The logout process follows the OpenID Connect specifications: +- [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) - [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html) - [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html) -**Post-logout redirect:** If you pass `post_logout_redirect_uri`, you must also include `id_token_hint` (the ID token from the login response). Requests with `post_logout_redirect_uri` but without `id_token_hint` will be rejected. - -
+
Query Parameters
Successful logout. The user will be redirected to complete the logout process.
- + \ No newline at end of file diff --git a/docs/oauth2_apis_versioned/revoke-oidc-session.api.mdx b/docs/oauth2_apis_versioned/revoke-oidc-session.api.mdx index 41713ff5..fef63f90 100644 --- a/docs/oauth2_apis_versioned/revoke-oidc-session.api.mdx +++ b/docs/oauth2_apis_versioned/revoke-oidc-session.api.mdx @@ -5,7 +5,7 @@ description: "This endpoint handles the user logout process in Quran.Foundation' sidebar_label: "OpenID Connect Logout" hide_title: true hide_table_of_contents: true -api: {"description":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nThe logout process follows the OpenID Connect specifications:\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","operationId":"revokeOidcSession","responses":{"302":{"description":"Successful logout. The user will be redirected to complete the logout process."}},"tags":["OIDC"],"method":"get","path":"/oauth2/sessions/logout","servers":[{"url":"https://oauth2.quran.foundation","description":"Production Server"},{"url":"https://staging-oauth2.quran.foundation","description":"Staging Server"}],"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"},"basicAuth":{"type":"http","scheme":"basic","description":"Basic authentication for client credentials"}},"info":{"title":"OAuth2 APIs","version":"1.0.0","description":"Quran.Foundation OAuth2 APIs are a set of APIs that allow you to integrate your app with Quran.Foundation's OAuth2 capabilities. This includes endpoints for OpenID Connect Userinfo, OAuth2 Token Exchange, and OAuth2 Authorize. The APIs are designed to be simple and easy to use, with a focus on security and privacy. Integrating with Quran.Foundation's OAuth2 APIs is required to access Quran.Foundation's APIs."},"postman":{"name":"OpenID Connect Logout","description":{"content":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nThe logout process follows the OpenID Connect specifications:\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","type":"text/plain"},"url":{"path":["oauth2","sessions","logout"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"method":"GET"}} +api: {"description":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nTo redirect users back to your app after logout, include `post_logout_redirect_uri`. The redirect URI must be pre-registered in your OAuth2 client configuration.\n\nThe logout process follows the OpenID Connect specifications:\n- [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","operationId":"revokeOidcSession","parameters":[{"in":"query","name":"id_token_hint","description":"The ID token received during authentication. Optional but recommended for identifying the user session.","required":false,"schema":{"type":"string","example":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}},{"in":"query","name":"post_logout_redirect_uri","description":"Where to redirect the user after logout. Must be pre-registered in your OAuth2 client's `post_logout_redirect_uris`.","required":false,"schema":{"type":"string","example":"https://your-app.com/"}},{"in":"query","name":"state","description":"Opaque value passed back to the `post_logout_redirect_uri` for CSRF protection.","required":false,"schema":{"type":"string","example":"af0ifjsldkj"}}],"responses":{"302":{"description":"Successful logout. The user will be redirected to complete the logout process."}},"tags":["OIDC"],"method":"get","path":"/oauth2/sessions/logout","servers":[{"url":"https://oauth2.quran.foundation","description":"Production Server"},{"url":"https://staging-oauth2.quran.foundation","description":"Staging Server"}],"securitySchemes":{"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token authentication"},"basicAuth":{"type":"http","scheme":"basic","description":"Basic authentication for client credentials"}},"info":{"title":"OAuth2 APIs","version":"1.0.0","description":"Quran.Foundation OAuth2 APIs are a set of APIs that allow you to integrate your app with Quran.Foundation's OAuth2 capabilities. This includes endpoints for OpenID Connect Userinfo, OAuth2 Token Exchange, and OAuth2 Authorize. The APIs are designed to be simple and easy to use, with a focus on security and privacy. Integrating with Quran.Foundation's OAuth2 APIs is required to access Quran.Foundation's APIs."},"postman":{"name":"OpenID Connect Logout","description":{"content":"This endpoint handles the user logout process in Quran.Foundation's OAuth2 & OpenID Connect system. When called, it:\n\n1. Ends the user's current session\n2. Revokes associated access and refresh tokens\n\nTo redirect users back to your app after logout, include `post_logout_redirect_uri`. The redirect URI must be pre-registered in your OAuth2 client configuration.\n\nThe logout process follows the OpenID Connect specifications:\n- [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html)\n- [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html)\n- [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html)","type":"text/plain"},"url":{"path":["oauth2","sessions","logout"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The ID token received during authentication. Optional but recommended for identifying the user session.","type":"text/plain"},"key":"id_token_hint","value":""},{"disabled":false,"description":{"content":"Where to redirect the user after logout. Must be pre-registered in your OAuth2 client's `post_logout_redirect_uris`.","type":"text/plain"},"key":"post_logout_redirect_uri","value":""},{"disabled":false,"description":{"content":"Opaque value passed back to the `post_logout_redirect_uri` for CSRF protection.","type":"text/plain"},"key":"state","value":""}],"variable":[]},"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/oauth2_apis_versioned/oauth-2-apis custom_edit_url: null @@ -29,15 +29,16 @@ This endpoint handles the user logout process in Quran.Foundation's OAuth2 & Ope 1. Ends the user's current session 2. Revokes associated access and refresh tokens +To redirect users back to your app after logout, include `post_logout_redirect_uri`. The redirect URI must be pre-registered in your OAuth2 client configuration. + The logout process follows the OpenID Connect specifications: +- [RP-Initiated Logout](https://openid.net/specs/openid-connect-rpinitiated-1_0.html) - [Front-Channel Logout](https://openid.net/specs/openid-connect-frontchannel-1_0.html) - [Back-Channel Logout](https://openid.net/specs/openid-connect-backchannel-1_0.html) -**Post-logout redirect:** If you pass `post_logout_redirect_uri`, you must also include `id_token_hint` (the ID token from the login response). Requests with `post_logout_redirect_uri` but without `id_token_hint` will be rejected. - -
+
Query Parameters
Successful logout. The user will be redirected to complete the logout process.
- + \ No newline at end of file diff --git a/docs/search_apis_versioned/1.0.0/search-controller-search.api.mdx b/docs/search_apis_versioned/1.0.0/search-controller-search.api.mdx index b5cb8b46..5fe8549c 100644 --- a/docs/search_apis_versioned/1.0.0/search-controller-search.api.mdx +++ b/docs/search_apis_versioned/1.0.0/search-controller-search.api.mdx @@ -5,7 +5,7 @@ description: "Search for verses, chapters, juz, pages, and other Quran content. sidebar_label: "Search Quran content" hide_title: true hide_table_of_contents: true -api: {"operationId":"SearchController_search","description":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","parameters":[{"name":"mode","required":true,"in":"query","description":"Search mode - quick for navigation/autocomplete, advanced for detailed results","example":"quick","schema":{"enum":["advanced","quick"],"type":"string"}},{"name":"query","required":true,"in":"query","description":"Search query string","example":"mercy","schema":{"type":"string"}},{"name":"filter_translations","required":false,"in":"query","description":"Comma-separated translation IDs to filter by","example":"131,20","schema":{"type":"string"}},{"name":"exact_matches_only","required":false,"in":"query","description":"Return only exact matches (advanced mode only)","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"get_text","required":false,"in":"query","description":"Include full verse text in results","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"highlight","required":false,"in":"query","description":"Highlight matching text in results","schema":{"default":"1","enum":["0","1"],"type":"string"}},{"name":"navigationalResultsNumber","required":false,"in":"query","description":"Number of navigational results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":5,"type":"number"}},{"name":"versesResultsNumber","required":false,"in":"query","description":"Number of verse results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"indexes","required":false,"in":"query","description":"Comma-separated list of indexes to search (quick mode only)","example":"quran,translations","schema":{"type":"string"}},{"name":"translation_ids","required":false,"in":"query","description":"Comma-separated translation IDs","example":"131,20,85","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"description":"Pagination metadata for the results","allOf":[{"type":"object","properties":{"current_page":{"type":"number","example":1,"description":"Current page number"},"next_page":{"type":"number","example":2,"nullable":true,"description":"Next page number, null if on last page"},"per_page":{"type":"number","example":20,"description":"Results per page"},"total_pages":{"type":"number","example":5,"description":"Total number of pages"},"total_records":{"type":"number","example":100,"description":"Total number of matching records"}},"required":["current_page","per_page","total_pages","total_records"],"title":"SearchPaginationDto"}]},"result":{"description":"Search results containing navigation links and verse matches","allOf":[{"type":"object","properties":{"navigation":{"description":"Quick navigation results (chapters, juz, pages, etc.)","example":[{"result_type":"surah","key":1,"name":"Al-Fatihah","isArabic":false},{"result_type":"surah","key":36,"name":"Ya-Sin","isArabic":false}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}},"verses":{"description":"Verse results matching the search query","example":[{"result_type":"ayah","key":"1:1","name":"بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ","isArabic":true},{"result_type":"ayah","key":"2:163","name":"وَإِلَٰهُكُمْ إِلَٰهٌ وَاحِدٌ ۖ لَّا إِلَٰهَ إِلَّا هُوَ الرَّحْمَٰنُ الرَّحِيمُ","isArabic":true}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}}},"required":["navigation","verses"],"title":"SearchResultsDto"}]}},"required":["pagination","result"],"title":"SearchResponseDto"}}}},"400":{"description":"Invalid search parameters - check required fields mode and query"},"401":{"description":"Unauthorized - missing or invalid x-auth-token header"},"403":{"description":"Forbidden - token does not have the required \"search\" scope"}},"tags":["Search"],"method":"get","path":"/v1/search","servers":[{"url":"https://apis-prelive.quran.foundation/search","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/search","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"info":{"title":"Quran.Foundation Search API","description":"Quran.Foundation Search API provides programmatic access to search Quran content including verses, chapters, juz, pages, and translations. This is distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis).\n\n## How to get access\n\nWe 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). The required scope is [`search`](/docs/user_related_apis_versioned/scopes#search).","version":"1.0","contact":{}},"postman":{"name":"Search Quran content","description":{"content":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","type":"text/plain"},"url":{"path":["v1","search"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Search mode - quick for navigation/autocomplete, advanced for detailed results","type":"text/plain"},"key":"mode","value":""},{"disabled":false,"description":{"content":"(Required) Search query string","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs to filter by","type":"text/plain"},"key":"filter_translations","value":""},{"disabled":false,"description":{"content":"Return only exact matches (advanced mode only)","type":"text/plain"},"key":"exact_matches_only","value":""},{"disabled":false,"description":{"content":"Include full verse text in results","type":"text/plain"},"key":"get_text","value":""},{"disabled":false,"description":{"content":"Highlight matching text in results","type":"text/plain"},"key":"highlight","value":""},{"disabled":false,"description":{"content":"Number of navigational results to return (quick mode only)","type":"text/plain"},"key":"navigationalResultsNumber","value":""},{"disabled":false,"description":{"content":"Number of verse results to return (quick mode only)","type":"text/plain"},"key":"versesResultsNumber","value":""},{"disabled":false,"description":{"content":"Comma-separated list of indexes to search (quick mode only)","type":"text/plain"},"key":"indexes","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs","type":"text/plain"},"key":"translation_ids","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"operationId":"SearchController_search","description":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","parameters":[{"name":"mode","required":true,"in":"query","description":"Search mode - quick for navigation/autocomplete, advanced for detailed results","example":"quick","schema":{"enum":["advanced","quick"],"type":"string"}},{"name":"query","required":true,"in":"query","description":"Search query string","example":"mercy","schema":{"type":"string"}},{"name":"filter_translations","required":false,"in":"query","description":"Comma-separated translation IDs to filter by","example":"131,20","schema":{"type":"string"}},{"name":"exact_matches_only","required":false,"in":"query","description":"Return only exact matches (advanced mode only)","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"get_text","required":false,"in":"query","description":"Include full verse text in results","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"highlight","required":false,"in":"query","description":"Highlight matching text in results","schema":{"default":"1","enum":["0","1"],"type":"string"}},{"name":"navigationalResultsNumber","required":false,"in":"query","description":"Number of navigational results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":5,"type":"number"}},{"name":"versesResultsNumber","required":false,"in":"query","description":"Number of verse results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"indexes","required":false,"in":"query","description":"Comma-separated list of indexes to search (quick mode only)","example":"quran,translations","schema":{"type":"string"}},{"name":"translation_ids","required":false,"in":"query","description":"Comma-separated translation IDs","example":"131,20,85","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"description":"Pagination metadata for the results","allOf":[{"type":"object","properties":{"current_page":{"type":"number","example":1,"description":"Current page number"},"next_page":{"type":"number","example":2,"nullable":true,"description":"Next page number, null if on last page"},"per_page":{"type":"number","example":20,"description":"Results per page"},"total_pages":{"type":"number","example":5,"description":"Total number of pages"},"total_records":{"type":"number","example":100,"description":"Total number of matching records"}},"required":["current_page","per_page","total_pages","total_records"],"title":"SearchPaginationDto"}]},"result":{"description":"Search results containing navigation links and verse matches","allOf":[{"type":"object","properties":{"navigation":{"description":"Quick navigation results (chapters, juz, pages, etc.)","example":[{"result_type":"surah","key":1,"name":"Al-Fatihah","isArabic":false},{"result_type":"surah","key":36,"name":"Ya-Sin","isArabic":false}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"arabic":{"type":"string","example":"الفاتحة","description":"Original Arabic text of the result"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}},"verses":{"description":"Verse results matching the search query","example":[{"result_type":"ayah","key":"1:1","name":"بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ","isArabic":true},{"result_type":"ayah","key":"2:163","name":"وَإِلَٰهُكُمْ إِلَٰهٌ وَاحِدٌ ۖ لَّا إِلَٰهَ إِلَّا هُوَ الرَّحْمَٰنُ الرَّحِيمُ","isArabic":true}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"arabic":{"type":"string","example":"الفاتحة","description":"Original Arabic text of the result"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}}},"required":["navigation","verses"],"title":"SearchResultsDto"}]}},"required":["pagination","result"],"title":"SearchResponseDto"}}}},"400":{"description":"Invalid search parameters - check required fields mode and query"},"401":{"description":"Unauthorized - missing or invalid x-auth-token header"},"403":{"description":"Forbidden - token does not have the required \"search\" scope"}},"tags":["Search"],"method":"get","path":"/v1/search","servers":[{"url":"https://apis-prelive.quran.foundation/search","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/search","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"info":{"title":"Quran.Foundation Search API","description":"Quran.Foundation Search API provides programmatic access to search Quran content including verses, chapters, juz, pages, and translations. This is distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis).\n\n## How to get access\n\nWe 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). The required scope is [`search`](/docs/user_related_apis_versioned/scopes#search).","version":"1.0","contact":{}},"postman":{"name":"Search Quran content","description":{"content":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","type":"text/plain"},"url":{"path":["v1","search"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Search mode - quick for navigation/autocomplete, advanced for detailed results","type":"text/plain"},"key":"mode","value":""},{"disabled":false,"description":{"content":"(Required) Search query string","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs to filter by","type":"text/plain"},"key":"filter_translations","value":""},{"disabled":false,"description":{"content":"Return only exact matches (advanced mode only)","type":"text/plain"},"key":"exact_matches_only","value":""},{"disabled":false,"description":{"content":"Include full verse text in results","type":"text/plain"},"key":"get_text","value":""},{"disabled":false,"description":{"content":"Highlight matching text in results","type":"text/plain"},"key":"highlight","value":""},{"disabled":false,"description":{"content":"Number of navigational results to return (quick mode only)","type":"text/plain"},"key":"navigationalResultsNumber","value":""},{"disabled":false,"description":{"content":"Number of verse results to return (quick mode only)","type":"text/plain"},"key":"versesResultsNumber","value":""},{"disabled":false,"description":{"content":"Comma-separated list of indexes to search (quick mode only)","type":"text/plain"},"key":"indexes","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs","type":"text/plain"},"key":"translation_ids","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/search_apis_versioned/1.0.0/quran-foundation-search-api custom_edit_url: null @@ -76,7 +76,7 @@ Key for navigation (chapter number, verse key like "1:1", juz number, etc.) Key for navigation (chapter number, verse key like "1:1", juz number, etc.) -
  • ]
    • verses object[] required
    +
  • ]
    • verses object[] required
    Verse results matching the search query @@ -92,7 +92,7 @@ Key for navigation (chapter number, verse key like "1:1", juz number, etc.) Key for navigation (chapter number, verse key like "1:1", juz number, etc.) -
  • ]
    • +
  • ]
    • Invalid search parameters - check required fields mode and query diff --git a/docs/search_apis_versioned/search-controller-search.api.mdx b/docs/search_apis_versioned/search-controller-search.api.mdx index 1e984686..f86f841e 100644 --- a/docs/search_apis_versioned/search-controller-search.api.mdx +++ b/docs/search_apis_versioned/search-controller-search.api.mdx @@ -5,7 +5,7 @@ description: "Search for verses, chapters, juz, pages, and other Quran content. sidebar_label: "Search Quran content" hide_title: true hide_table_of_contents: true -api: {"operationId":"SearchController_search","description":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","parameters":[{"name":"mode","required":true,"in":"query","description":"Search mode - quick for navigation/autocomplete, advanced for detailed results","example":"quick","schema":{"enum":["advanced","quick"],"type":"string"}},{"name":"query","required":true,"in":"query","description":"Search query string","example":"mercy","schema":{"type":"string"}},{"name":"filter_translations","required":false,"in":"query","description":"Comma-separated translation IDs to filter by","example":"131,20","schema":{"type":"string"}},{"name":"exact_matches_only","required":false,"in":"query","description":"Return only exact matches (advanced mode only)","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"get_text","required":false,"in":"query","description":"Include full verse text in results","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"highlight","required":false,"in":"query","description":"Highlight matching text in results","schema":{"default":"1","enum":["0","1"],"type":"string"}},{"name":"navigationalResultsNumber","required":false,"in":"query","description":"Number of navigational results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":5,"type":"number"}},{"name":"versesResultsNumber","required":false,"in":"query","description":"Number of verse results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"indexes","required":false,"in":"query","description":"Comma-separated list of indexes to search (quick mode only)","example":"quran,translations","schema":{"type":"string"}},{"name":"translation_ids","required":false,"in":"query","description":"Comma-separated translation IDs","example":"131,20,85","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"description":"Pagination metadata for the results","allOf":[{"type":"object","properties":{"current_page":{"type":"number","example":1,"description":"Current page number"},"next_page":{"type":"number","example":2,"nullable":true,"description":"Next page number, null if on last page"},"per_page":{"type":"number","example":20,"description":"Results per page"},"total_pages":{"type":"number","example":5,"description":"Total number of pages"},"total_records":{"type":"number","example":100,"description":"Total number of matching records"}},"required":["current_page","per_page","total_pages","total_records"],"title":"SearchPaginationDto"}]},"result":{"description":"Search results containing navigation links and verse matches","allOf":[{"type":"object","properties":{"navigation":{"description":"Quick navigation results (chapters, juz, pages, etc.)","example":[{"result_type":"surah","key":1,"name":"Al-Fatihah","isArabic":false},{"result_type":"surah","key":36,"name":"Ya-Sin","isArabic":false}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}},"verses":{"description":"Verse results matching the search query","example":[{"result_type":"ayah","key":"1:1","name":"بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ","isArabic":true},{"result_type":"ayah","key":"2:163","name":"وَإِلَٰهُكُمْ إِلَٰهٌ وَاحِدٌ ۖ لَّا إِلَٰهَ إِلَّا هُوَ الرَّحْمَٰنُ الرَّحِيمُ","isArabic":true}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}}},"required":["navigation","verses"],"title":"SearchResultsDto"}]}},"required":["pagination","result"],"title":"SearchResponseDto"}}}},"400":{"description":"Invalid search parameters - check required fields mode and query"},"401":{"description":"Unauthorized - missing or invalid x-auth-token header"},"403":{"description":"Forbidden - token does not have the required \"search\" scope"}},"tags":["Search"],"method":"get","path":"/v1/search","servers":[{"url":"https://apis-prelive.quran.foundation/search","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/search","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"info":{"title":"Quran.Foundation Search API","description":"Quran.Foundation Search API provides programmatic access to search Quran content including verses, chapters, juz, pages, and translations. This is distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis).\n\n## How to get access\n\nWe 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). The required scope is [`search`](/docs/user_related_apis_versioned/scopes#search).","version":"1.0","contact":{}},"postman":{"name":"Search Quran content","description":{"content":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","type":"text/plain"},"url":{"path":["v1","search"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Search mode - quick for navigation/autocomplete, advanced for detailed results","type":"text/plain"},"key":"mode","value":""},{"disabled":false,"description":{"content":"(Required) Search query string","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs to filter by","type":"text/plain"},"key":"filter_translations","value":""},{"disabled":false,"description":{"content":"Return only exact matches (advanced mode only)","type":"text/plain"},"key":"exact_matches_only","value":""},{"disabled":false,"description":{"content":"Include full verse text in results","type":"text/plain"},"key":"get_text","value":""},{"disabled":false,"description":{"content":"Highlight matching text in results","type":"text/plain"},"key":"highlight","value":""},{"disabled":false,"description":{"content":"Number of navigational results to return (quick mode only)","type":"text/plain"},"key":"navigationalResultsNumber","value":""},{"disabled":false,"description":{"content":"Number of verse results to return (quick mode only)","type":"text/plain"},"key":"versesResultsNumber","value":""},{"disabled":false,"description":{"content":"Comma-separated list of indexes to search (quick mode only)","type":"text/plain"},"key":"indexes","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs","type":"text/plain"},"key":"translation_ids","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"operationId":"SearchController_search","description":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","parameters":[{"name":"mode","required":true,"in":"query","description":"Search mode - quick for navigation/autocomplete, advanced for detailed results","example":"quick","schema":{"enum":["advanced","quick"],"type":"string"}},{"name":"query","required":true,"in":"query","description":"Search query string","example":"mercy","schema":{"type":"string"}},{"name":"filter_translations","required":false,"in":"query","description":"Comma-separated translation IDs to filter by","example":"131,20","schema":{"type":"string"}},{"name":"exact_matches_only","required":false,"in":"query","description":"Return only exact matches (advanced mode only)","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"get_text","required":false,"in":"query","description":"Include full verse text in results","schema":{"default":"0","enum":["0","1"],"type":"string"}},{"name":"highlight","required":false,"in":"query","description":"Highlight matching text in results","schema":{"default":"1","enum":["0","1"],"type":"string"}},{"name":"navigationalResultsNumber","required":false,"in":"query","description":"Number of navigational results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":5,"type":"number"}},{"name":"versesResultsNumber","required":false,"in":"query","description":"Number of verse results to return (quick mode only)","schema":{"minimum":1,"maximum":50,"default":20,"type":"number"}},{"name":"indexes","required":false,"in":"query","description":"Comma-separated list of indexes to search (quick mode only)","example":"quran,translations","schema":{"type":"string"}},{"name":"translation_ids","required":false,"in":"query","description":"Comma-separated translation IDs","example":"131,20,85","schema":{"type":"string"}}],"responses":{"200":{"description":"Search results returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"pagination":{"description":"Pagination metadata for the results","allOf":[{"type":"object","properties":{"current_page":{"type":"number","example":1,"description":"Current page number"},"next_page":{"type":"number","example":2,"nullable":true,"description":"Next page number, null if on last page"},"per_page":{"type":"number","example":20,"description":"Results per page"},"total_pages":{"type":"number","example":5,"description":"Total number of pages"},"total_records":{"type":"number","example":100,"description":"Total number of matching records"}},"required":["current_page","per_page","total_pages","total_records"],"title":"SearchPaginationDto"}]},"result":{"description":"Search results containing navigation links and verse matches","allOf":[{"type":"object","properties":{"navigation":{"description":"Quick navigation results (chapters, juz, pages, etc.)","example":[{"result_type":"surah","key":1,"name":"Al-Fatihah","isArabic":false},{"result_type":"surah","key":36,"name":"Ya-Sin","isArabic":false}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"arabic":{"type":"string","example":"الفاتحة","description":"Original Arabic text of the result"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}},"verses":{"description":"Verse results matching the search query","example":[{"result_type":"ayah","key":"1:1","name":"بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ","isArabic":true},{"result_type":"ayah","key":"2:163","name":"وَإِلَٰهُكُمْ إِلَٰهٌ وَاحِدٌ ۖ لَّا إِلَٰهَ إِلَّا هُوَ الرَّحْمَٰنُ الرَّحِيمُ","isArabic":true}],"type":"array","items":{"type":"object","properties":{"result_type":{"type":"string","enum":["surah","juz","hizb","ayah","rub_el_hizb","search_page","page","range","quran_range"],"example":"surah","description":"Type of result - determines how to navigate/display"},"key":{"oneOf":[{"type":"number"},{"type":"string"}],"example":1,"description":"Key for navigation (chapter number, verse key like \"1:1\", juz number, etc.)"},"name":{"type":"string","example":"Al-Fatihah","description":"Display name of the result (chapter name, verse text preview, etc.)"},"arabic":{"type":"string","example":"الفاتحة","description":"Original Arabic text of the result"},"isArabic":{"type":"boolean","example":true,"description":"True if the name contains Arabic text"},"isTransliteration":{"type":"boolean","example":false,"description":"True if the result is from transliteration matching"}},"required":["result_type","key","name"],"title":"SearchNavigationResultDto"}}},"required":["navigation","verses"],"title":"SearchResultsDto"}]}},"required":["pagination","result"],"title":"SearchResponseDto"}}}},"400":{"description":"Invalid search parameters - check required fields mode and query"},"401":{"description":"Unauthorized - missing or invalid x-auth-token header"},"403":{"description":"Forbidden - token does not have the required \"search\" scope"}},"tags":["Search"],"method":"get","path":"/v1/search","servers":[{"url":"https://apis-prelive.quran.foundation/search","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/search","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"info":{"title":"Quran.Foundation Search API","description":"Quran.Foundation Search API provides programmatic access to search Quran content including verses, chapters, juz, pages, and translations. This is distinct from user-specific data like notes and bookmarks provided by [User-related APIs](/docs/category/user-related-apis).\n\n## How to get access\n\nWe 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). The required scope is [`search`](/docs/user_related_apis_versioned/scopes#search).","version":"1.0","contact":{}},"postman":{"name":"Search Quran content","description":{"content":"\nSearch for verses, chapters, juz, pages, and other Quran content. This is the primary search API used by Quran.com.\n\n## Use Cases\n\n### 1. Command Bar / Search-as-you-type (Quick Mode)\nUsed in Quran.com's command bar for instant navigation. Returns both navigational results (chapters, juz, pages) and verse matches.\n\n```\nGET /v1/search?mode=quick&query=fatiha&navigationalResultsNumber=5&versesResultsNumber=10\n```\n\n### 2. Search Results Page (Advanced Mode)\nUsed for the full search results page with pagination and detailed verse results.\n\n```\nGET /v1/search?mode=advanced&query=mercy&page=1&size=20&translation_ids=131,20\n```\n\n### 3. Search with Exact Matching\nFor precise search queries, use exact_matches_only in advanced mode.\n\n```\nGET /v1/search?mode=advanced&query=الرحمن&exact_matches_only=1\n```\n\n## Response Structure\n- **navigation**: Quick links to chapters, juz, pages matching the query\n- **verses**: Individual verse matches with optional highlighting\n- **pagination**: Standard pagination info for result sets\n ","type":"text/plain"},"url":{"path":["v1","search"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Search mode - quick for navigation/autocomplete, advanced for detailed results","type":"text/plain"},"key":"mode","value":""},{"disabled":false,"description":{"content":"(Required) Search query string","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs to filter by","type":"text/plain"},"key":"filter_translations","value":""},{"disabled":false,"description":{"content":"Return only exact matches (advanced mode only)","type":"text/plain"},"key":"exact_matches_only","value":""},{"disabled":false,"description":{"content":"Include full verse text in results","type":"text/plain"},"key":"get_text","value":""},{"disabled":false,"description":{"content":"Highlight matching text in results","type":"text/plain"},"key":"highlight","value":""},{"disabled":false,"description":{"content":"Number of navigational results to return (quick mode only)","type":"text/plain"},"key":"navigationalResultsNumber","value":""},{"disabled":false,"description":{"content":"Number of verse results to return (quick mode only)","type":"text/plain"},"key":"versesResultsNumber","value":""},{"disabled":false,"description":{"content":"Comma-separated list of indexes to search (quick mode only)","type":"text/plain"},"key":"indexes","value":""},{"disabled":false,"description":{"content":"Comma-separated translation IDs","type":"text/plain"},"key":"translation_ids","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/search_apis_versioned/quran-foundation-search-api custom_edit_url: null @@ -76,7 +76,7 @@ Key for navigation (chapter number, verse key like "1:1", juz number, etc.) Key for navigation (chapter number, verse key like "1:1", juz number, etc.) -
  • ]
    • verses object[] required
    +
  • ]
    • verses object[] required
    Verse results matching the search query @@ -92,7 +92,7 @@ Key for navigation (chapter number, verse key like "1:1", juz number, etc.) Key for navigation (chapter number, verse key like "1:1", juz number, etc.) -
  • ]
    • +
  • ]
    • Invalid search parameters - check required fields mode and query diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx index 2ff8171f..ca64800d 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkg2we7y00082o5reyma8z73"},"required":true,"description":"The Id of the collection to be added."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkthm7ui0008r4jq9bmzc243"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
    Path Parameters
    Request Body
      anyOf
    +
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    Request has been handled successfully. -
    Schema
      data object
    +
    Response Headers
    • X-Mutation-At string
      + +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
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx index 885ba7b5..852fdb7a 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":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}}}}},"method":"post","path":"/v1/collections/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Create a new collection under user's account. -
    Request Body
    +
    Query Parameters
    Request Body
    Request has been handled successfully. -
    Schema
      data object
    +
    Response Headers
    • X-Mutation-At string
      + +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
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx index b2d5d669..84f8d8c8 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx @@ -5,7 +5,7 @@ description: "Add a new note." sidebar_label: "Add note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Add a new note.","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/notes/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"tags":["Notes"],"description":"Add a new note.","parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a new note. -
    Request Body
      = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
      attachedEntity object
      entityMetadata object
      +
      Query Parameters
      Request Body
        = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
        attachedEntity object
        entityMetadata object
        Additional metadata for the attached entity. @@ -34,7 +34,11 @@ Additional metadata for the attached entity. Request has been handled successfully. -
        Schema
          data object
          = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
          attachedEntities object[]
          +
          Response Headers
          • X-Mutation-At string
            + +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
            data object
            = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
            attachedEntities object[]
            An array of attached entities associated with the note. diff --git a/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx index 67eb0f20..1e2706ca 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx @@ -5,7 +5,7 @@ description: "Add or update one user preferences group like favorite Tafsirs or sidebar_label: "Add or update preference" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update one user preferences group like favorite Tafsirs or translations.","tags":["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":{"type":"object","properties":{"group":{"type":"string","enum":["tafsirs","translations","audio","theme","quranReaderStyles","reading","language"],"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,"anyOf":[{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":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":["preference updated"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/preferences/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"group":"tafsirs","key":"selectedTafsirs","value":"[\"en-tafisr-ibn-kathir\"]"},"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 ## 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"},"postman":{"name":"Add or update preference","description":{"content":"Add or update one user preferences group like favorite Tafsirs or translations.","type":"text/plain"},"url":{"path":["v1","preferences",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update one user preferences group like favorite Tafsirs or translations.","tags":["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":{"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,"anyOf":[{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["key"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":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":["preference updated"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"group":"tafsirs","key":"selectedTafsirs","value":"[\"en-tafisr-ibn-kathir\"]"},"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 ## 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"},"postman":{"name":"Add or update preference","description":{"content":"Add or update one user preferences group like favorite Tafsirs or translations.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one user preferences group like favorite Tafsirs or translations. -
            Query Parameters
            Request Body
              anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>
            +
            Query Parameters
            Request Body
              anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
            Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/add-or-update-user-reading-session.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-or-update-user-reading-session.api.mdx index afd7c912..62ff0701 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-or-update-user-reading-session.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-or-update-user-reading-session.api.mdx @@ -5,7 +5,7 @@ description: "Create or update an existing reading session. Reading session is u sidebar_label: "Add or update user reading session" hide_title: true hide_table_of_contents: true -api: {"description":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","tags":["Reading Sessions"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chapterNumber":{"type":"integer","minimum":1,"description":"The Surah number to be added to reading session."},"verseNumber":{"type":"integer","minimum":1,"description":"The Ayah number to be added to reading session."}},"required":["chapterNumber","verseNumber"],"additionalProperties":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":["reading session created"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/reading-sessions/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"chapterNumber":0,"verseNumber":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 ## 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"},"postman":{"name":"Add or update user reading session","description":{"content":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","type":"text/plain"},"url":{"path":["v1","reading-sessions",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","tags":["Reading Sessions"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chapterNumber":{"type":"integer","minimum":1,"description":"The Surah number to be added to reading session."},"verseNumber":{"type":"integer","minimum":1,"description":"The Ayah number to be added to reading session."}},"required":["chapterNumber","verseNumber"],"additionalProperties":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":["reading session created"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"chapterNumber":0,"verseNumber":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 ## 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"},"postman":{"name":"Add or update user reading session","description":{"content":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null diff --git a/docs/user_related_apis_versioned/1.0.0/add-update-activity-day.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-update-activity-day.api.mdx index 8d73a8c4..73fb512a 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-update-activity-day.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-update-activity-day.api.mdx @@ -5,7 +5,7 @@ description: "Add or update an activity day." sidebar_label: "Add/update activity day" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update an activity day.","tags":["Activity Days"],"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":"The date of the activity day, can be today or a past date. If not passed, default to today","example":"2023-09-01"},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The type of the activity day","example":"QURAN"}},"required":["type"],"additionalProperties":false,"oneOf":[{"type":"object","required":["seconds","ranges","mushafId"],"additionalProperties":false,"title":"QURAN"}]}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/activity-days/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"date":"2023-09-01","type":"QURAN","seconds":5,"ranges":["1:5-1:10"],"mushafId":4},"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 ## 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"},"postman":{"name":"Add/update activity day","description":{"content":"Add or update an activity day.","type":"text/plain"},"url":{"path":["v1","activity-days",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update an activity day.","tags":["Activity Days"],"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":"The date of the activity day, can be today or a past date. If not passed, default to today","example":"2023-09-01"},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The type of the activity day","example":"QURAN"}},"required":["type"],"additionalProperties":false,"oneOf":[{"type":"object","required":["seconds","ranges","mushafId"],"additionalProperties":false,"title":"QURAN"}]}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"date":"2023-09-01","type":"QURAN","seconds":5,"ranges":["1:5-1:10"],"mushafId":4},"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 ## 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"},"postman":{"name":"Add/update activity day","description":{"content":"Add or update an activity day.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null diff --git a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx index 0219c0f5..8b6cb3db 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"post","path":"/v1/bookmarks/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Add a bookmark by details. -
            Request Body
              anyOf
            +
            Query Parameters
            Request Body
              anyOf
            Request has been handled successfully. -
            Schema
              data object
            +
            Response Headers
            • X-Mutation-At string
              + +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
              data object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx b/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx index e27fcba8..6b8069bb 100644 --- a/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Add or update one or more user preferences groups like favorite Ta sidebar_label: "Bulk add or update preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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"}},"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale"],"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}},"additionalProperties":false,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"theme":{"type":"auto"},"reading":{"readingPreference":"translation","selectedWordByWordLocale":"en","wordClickFunctionality":"play-audio","isReadingByRevelationOrder":true,"wordByWordContentType":["translation"],"wordByWordDisplay":["tooltip"],"wordByWordTooltipContentType":["translation"],"wordByWordInlineContentType":[],"selectedReadingTranslation":"131"},"quranReaderStyles":{"tafsirFontScale":3,"quranTextFontScale":3,"translationFontScale":3,"wordByWordFontScale":3,"quranFont":"code_v1","mushafLines":"16_lines"},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"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,"quranFont":"code_v1","mushafLines":"16_lines"},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"},"userHasCustomised":{"userHasCustomised":false}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one or more user preferences groups like favorite Tafsirs and translations. -
            Query Parameters
            Request Body
              theme object
              reading object
              quranReaderStyles object
              = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>
              translations object
              tafsirs object
              audio object
              language object
            +
            Query Parameters
            Request Body
              theme object
              reading object
              = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
              quranReaderStyles object
              = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
              translations object
              tafsirs object
              audio object
              language object
              userHasCustomised object
            Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx index 46c57501..67ecdade 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
            Schema
              comment object required
              author object
              avatarUrls object required
              mentions object[]
            • Array [
              • avatarUrls object required
            • ]
              • tags object[]
            • Array [
            • ]
            +
            Schema
              comment object required
              author object
              avatarUrls object required
              mentions object[]
            • Array [
              • avatarUrls object required
            • ]
              • tags object[]
            • Array [
            • ]
            Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx index 1098ff46..d06b7819 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
            Schema
              replies object[] required
            • Array [
              • author object
              avatarUrls object required
              mentions object[]
            • Array [
              • avatarUrls object required
            • ]
              • tags object[]
            • Array [
            • ]
            • ]
              • comment object required
              author object
              avatarUrls object required
              mentions object[]
            • Array [
              • avatarUrls object required
            • ]
              • tags object[]
            • Array [
            • ]
            +
            Schema
              replies object[] required
            • Array [
              • author object
              avatarUrls object required
              mentions object[]
            • Array [
              • avatarUrls object required
            • ]
              • tags object[]
            • Array [
            • ]
            • ]
              • comment object required
              author object
              avatarUrls object required
              mentions object[]
            • Array [
              • avatarUrls object required
            • ]
              • tags object[]
            • Array [
            • ]
            Parent comment not found diff --git a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx index c924826a..d2d149de 100644 --- a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmkg2wee5000d2o5r2resd1lm"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
            Schema
              data object
            +
            Schema
              data object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx index b272fac8..e0b4a4dd 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkg2wee5000d2o5r2resd1lm"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
            Path Parameters
            Query Parameters
            Header Parameters
            +
            Path Parameters
            Query Parameters
            Header Parameters
            Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx index 96a5188e..56913cf3 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkg2wdy700062o5r7kmica10"},"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}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkthm7rj0006r4jq3w04aolo"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
            Path Parameters
            +
            Path Parameters
            Query Parameters
            Request has been handled successfully. -
            Schema
              data object
            +
            Response Headers
            • X-Mutation-At string
              + +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
              data object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx index 24102104..b2daf219 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkg2we8q000a2o5rcu65crzk"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkg2we8q000b2o5r47opazrd"},"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}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7uu000ar4jqhzbcdlql"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkthm7uu000br4jqc2ec5h49"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
            Path Parameters
            +
            Path Parameters
            Query Parameters
            Request has been handled successfully. -
            Schema
              data object
            +
            Response Headers
            • X-Mutation-At string
              + +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
              data object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx index b4da3471..c3f07df8 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkg2we8d00092o5r2jux9iov"},"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}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7up0009r4jqfaqg4iha"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
            Path Parameters
            +
            Path Parameters
            Query Parameters
            Request has been handled successfully. -
            Schema
              data object
            +
            Response Headers
            • X-Mutation-At string
              + +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
              data object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx index 975b1901..41443ed5 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a note by its ID." sidebar_label: "Delete note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a note by its ID. -
            Path Parameters
            +
            Path Parameters
            Query Parameters
            Request has been handled successfully. -
            Schema
              data object
            +
            Response Headers
            • X-Mutation-At string
              + +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
              data object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx index 28fc44f0..7a98f519 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":"cmkg2wdks00042o5r0l5xfrpu"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
            Query Parameters
            +
            Query Parameters
            Request has been handled successfully. -
            Schema
              data object[]
            • Array [
              • ranges object
              +
              Schema
                data object[]
              • Array [
                • ranges object
                The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
              • ]
                • pagination object
              +
            • ]
              • pagination object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx index 5e455206..42fd78a3 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
            Query Parameters
            +
            Query Parameters
            Request has been handled successfully. -
            Schema
              data object[]
            • Array [
            • ]
              • pagination object
            +
            Schema
              data object[]
            • Array [
            • ]
              • pagination object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx index a6487da8..b7b193ec 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
            Query Parameters
            +
            Query Parameters
            Request has been handled successfully. -
            Schema
              data object[]
            • Array [
            • ]
              • pagination object
            +
            Schema
              data object[]
            • Array [
            • ]
              • pagination object
            The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx index c34d48d1..4b093ce9 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
          • ]
          • ]
          pagination object
        +
      • ]
      • ]
      pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx index f558da8a..f189a3f3 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":"object","properties":{"id":{"type":"string","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx index d36b7510..ac561174 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx index a78a9746..a89a82c6 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx index 4e80752a..2380d43d 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkg2weab000c2o5rbafhcreg"}},{"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkthm7vj000cr4jqdkfabg59"}},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx new file mode 100644 index 00000000..8e3a6a81 --- /dev/null +++ b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx @@ -0,0 +1,86 @@ +--- +id: get-mutations +title: "Get mutations" +description: "Get list of mutations that were applied to resources after a certain point in time." +sidebar_label: "Get mutations" +hide_title: true +hide_table_of_contents: true +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +sidebar_class_name: "get api-method" +info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis +custom_edit_url: null +--- + +import ApiTabs from "@theme/ApiTabs"; +import MimeTabs from "@theme/MimeTabs"; +import ParamsItem from "@theme/ParamsItem"; +import ResponseSamples from "@theme/ResponseSamples"; +import SchemaItem from "@theme/SchemaItem"; +import SchemaTabs from "@theme/SchemaTabs"; +import DiscriminatorTabs from "@theme/DiscriminatorTabs"; +import TabItem from "@theme/TabItem"; + +## Get mutations + + + +Get list of mutations that were applied to resources after a certain point in time. + +
    Query Parameters
    + +Request has been handled successfully. + +
    Schema
      data object
      + +Response schema for get mutations endpoint + +
      mutations object[]
      + +Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true. + +
    • Array [
      • data object
      + +The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. + +
    • ]
    + +The request is missing required parameters or is invalid. + +
    Schema
    + +The request is unauthorized. + +
    Schema
    + +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. + +
    Schema
    + +Not Found. The resource being accessed does not exist. + +
    Schema
    + +Validation Error. The request includes one or more invalid params. Please check the request params and try again. + +
    Schema
    + +Too many requests, please try again later. + +
    Schema
    + +Server Error. Something went wrong, try again later. + +
    Schema
    + +Invalid response from the upstream server + +
    Schema
    + +The server is currently unable to handle the request due to a temporary overload or scheduled maintenance + +
    Schema
    + +The server did not receive a timely response from the upstream server. + +
    Schema
    + \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx index 7cf5f8fa..c5b6a148 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx index cae78204..fd3f4498 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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 streak.","example":"cmkg2wf48000f2o5r97huaiw5"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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 streak.","example":"cmkthm85f000fr4jq7l9khj0j"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx index 19ef92cd..48c8a5b2 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkg2wdks00042o5r0l5xfrpu"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx index 76db9ab0..1d544ecb 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx index 6c6d476f..665984a2 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Get all user preferences like theme, favorite reciter, default lan sidebar_label: "Get user preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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"}},"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale"],"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}},"additionalProperties":false,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all user preferences like theme, favorite reciter, default language etc. Request has been handled successfully. -
    Schema
      data object
      theme object
      reading object
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
    +
    Schema
      data object
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx index 90184581..495172f7 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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","example":"cmkg2wf2r000e2o5r1bkbcm8w"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm84w000er4jq7r9u47p2"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx index a7c2f3ea..4030d313 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-19T08:00:56.127Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:58.670Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx index d5e2ac5d..e4aecc04 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-19T08:00:56.126Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:58.670Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx index ec85f582..e6373fb9 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx index d621d6db..40d64366 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx index 588d039a..264712c7 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx index db73368e..53d11e57 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx index be007927..bc240cab 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx index cf262e3f..f1c792d1 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx index 07e3b0e9..5cea55ea 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx b/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx index b0221f38..16af75da 100644 --- a/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx @@ -5,7 +5,7 @@ description: "Publish a note to QR." sidebar_label: "Publish note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Publish a note to QR. -
    Path Parameters
    Request Body
      = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
    +
    Path Parameters
    Query Parameters
    Request Body
      = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
    Request has been handled successfully. -
    Schema
      data object
      +
      Response Headers
      • X-Mutation-At string
        + +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
        data object
        Response object indicating the success of the note publishing operation and the optional post ID if successful. diff --git a/docs/user_related_apis_versioned/1.0.0/sidebar.js b/docs/user_related_apis_versioned/1.0.0/sidebar.js index 62ae72a2..38807e5d 100644 --- a/docs/user_related_apis_versioned/1.0.0/sidebar.js +++ b/docs/user_related_apis_versioned/1.0.0/sidebar.js @@ -1 +1 @@ -module.exports = [{"type":"doc","id":"user_related_apis_versioned/1.0.0/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file +module.exports = [{"type":"doc","id":"user_related_apis_versioned/1.0.0/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-delete-account","label":"Delete user account permanently","className":"api-method delete"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Sync","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-mutations","label":"Get mutations","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/sync-local-mutations","label":"Sync local mutations","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx new file mode 100644 index 00000000..45f0d059 --- /dev/null +++ b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx @@ -0,0 +1,94 @@ +--- +id: sync-local-mutations +title: "Sync local mutations" +description: "An endpoint to sync local mutations to the server." +sidebar_label: "Sync local mutations" +hide_title: true +hide_table_of_contents: true +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +sidebar_class_name: "post api-method" +info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis +custom_edit_url: null +--- + +import ApiTabs from "@theme/ApiTabs"; +import MimeTabs from "@theme/MimeTabs"; +import ParamsItem from "@theme/ParamsItem"; +import ResponseSamples from "@theme/ResponseSamples"; +import SchemaItem from "@theme/SchemaItem"; +import SchemaTabs from "@theme/SchemaTabs"; +import DiscriminatorTabs from "@theme/DiscriminatorTabs"; +import TabItem from "@theme/TabItem"; + +## Sync local mutations + + + +An endpoint to sync local mutations to the server. + +
        Query Parameters
        Request Body
          mutations object[] required
        • Array [
          • data object
          + +Resource data. Format depends on resource type. + +
        • ]
        + +Request has been handled successfully. + +
        Schema
          data object
          + +Response schema for post mutations endpoint + +
          mutations object[]
          + +Array of mutations that were successfully applied on the server. + +
        • Array [
          • data object
          + +The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. + +
        • ]
        + +The request is missing required parameters or is invalid. + +
        Schema
        + +The request is unauthorized. + +
        Schema
        + +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. + +
        Schema
        + +Not Found. The resource being accessed does not exist. + +
        Schema
        + +Out of Sync Error. The client lastMutationAt does not match server state. + +
        Schema
          error object
        + +Validation Error. The request includes one or more invalid params. + +
        Schema
          error object
        + +Too many requests, please try again later. + +
        Schema
        + +Server Error. Something went wrong, try again later. + +
        Schema
        + +Invalid response from the upstream server + +
        Schema
        + +The server is currently unable to handle the request due to a temporary overload or scheduled maintenance + +
        Schema
        + +The server did not receive a timely response from the upstream server. + +
        Schema
        + \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx index 4f7c251e..cbce4d8f 100644 --- a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
        Schema
        • Array [
        • ]
        +
      Schema
      • Array [
      • ]
      \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx index 56f6aa30..ad9bc24e 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkg2wee5000d2o5r2resd1lm"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        +
        Path Parameters
        Query Parameters
        Header Parameters
        Request Body
          amount object
          The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx index 9bef99bc..1c121996 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing collection." sidebar_label: "Update collection" hide_title: true hide_table_of_contents: true -api: {"description":"Update an existing collection.","tags":["Collections"],"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."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update an existing collection.","tags":["Collections"],"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."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the collection to be updated."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Update an existing collection. -
          Path Parameters
          Request Body
          +
          Path Parameters
          Query Parameters
          Request Body
          Request has been handled successfully. -
          Schema
            data object
          +
          Response Headers
          • X-Mutation-At string
            + +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
            data object
          The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx index 726b625f..c39cec5b 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Update a note by its ID." sidebar_label: "Update note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Update a note by its ID. -
          Path Parameters
          Request Body
            = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
          +
          Path Parameters
          Query Parameters
          Request Body
            = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
          Request has been handled successfully. -
          Schema
            data object
            = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
            attachedEntities object[]
            +
            Response Headers
            • X-Mutation-At string
              + +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
              data object
              = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
              attachedEntities object[]
              An array of attached entities associated with the note. diff --git a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx index f1ba7518..350c0ffc 100644 --- a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkg2we7y00082o5reyma8z73"},"required":true,"description":"The Id of the collection to be added."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkthm7ui0008r4jq9bmzc243"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
              Path Parameters
              Request Body
                anyOf
              +
              Path Parameters
              Query Parameters
              Request Body
                anyOf
              Request has been handled successfully. -
              Schema
                data object
              +
              Response Headers
              • X-Mutation-At string
                + +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
                data object
              The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/add-collection.api.mdx b/docs/user_related_apis_versioned/add-collection.api.mdx index 2c26dd54..952605a0 100644 --- a/docs/user_related_apis_versioned/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":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}}}}},"method":"post","path":"/v1/collections/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Create a new collection under user's account. -
              Request Body
              +
              Query Parameters
              Request Body
              Request has been handled successfully. -
              Schema
                data object
              +
              Response Headers
              • X-Mutation-At string
                + +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
                data object
              The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/add-note.api.mdx b/docs/user_related_apis_versioned/add-note.api.mdx index 9641c405..db45f525 100644 --- a/docs/user_related_apis_versioned/add-note.api.mdx +++ b/docs/user_related_apis_versioned/add-note.api.mdx @@ -5,7 +5,7 @@ description: "Add a new note." sidebar_label: "Add note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Add a new note.","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/notes/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"tags":["Notes"],"description":"Add a new note.","parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a new note. -
              Request Body
                = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
                attachedEntity object
                entityMetadata object
                +
                Query Parameters
                Request Body
                  = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
                  attachedEntity object
                  entityMetadata object
                  Additional metadata for the attached entity. @@ -34,7 +34,11 @@ Additional metadata for the attached entity. Request has been handled successfully. -
                  Schema
                    data object
                    = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
                    attachedEntities object[]
                    +
                    Response Headers
                    • X-Mutation-At string
                      + +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
                      data object
                      = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
                      attachedEntities object[]
                      An array of attached entities associated with the note. diff --git a/docs/user_related_apis_versioned/add-or-update-preference.api.mdx b/docs/user_related_apis_versioned/add-or-update-preference.api.mdx index df6c4e88..1015ab51 100644 --- a/docs/user_related_apis_versioned/add-or-update-preference.api.mdx +++ b/docs/user_related_apis_versioned/add-or-update-preference.api.mdx @@ -5,7 +5,7 @@ description: "Add or update one user preferences group like favorite Tafsirs or sidebar_label: "Add or update preference" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update one user preferences group like favorite Tafsirs or translations.","tags":["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":{"type":"object","properties":{"group":{"type":"string","enum":["tafsirs","translations","audio","theme","quranReaderStyles","reading","language"],"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,"anyOf":[{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":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":["preference updated"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/preferences/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"group":"tafsirs","key":"selectedTafsirs","value":"[\"en-tafisr-ibn-kathir\"]"},"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 ## 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"},"postman":{"name":"Add or update preference","description":{"content":"Add or update one user preferences group like favorite Tafsirs or translations.","type":"text/plain"},"url":{"path":["v1","preferences",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update one user preferences group like favorite Tafsirs or translations.","tags":["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":{"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,"anyOf":[{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["key"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":false},{"type":"object","required":["value"],"additionalProperties":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":["preference updated"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"group":"tafsirs","key":"selectedTafsirs","value":"[\"en-tafisr-ibn-kathir\"]"},"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 ## 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"},"postman":{"name":"Add or update preference","description":{"content":"Add or update one user preferences group like favorite Tafsirs or translations.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one user preferences group like favorite Tafsirs or translations. -
                      Query Parameters
                      Request Body
                        anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>
                      +
                      Query Parameters
                      Request Body
                        anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
                      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/add-or-update-user-reading-session.api.mdx b/docs/user_related_apis_versioned/add-or-update-user-reading-session.api.mdx index be68dca1..d1bfa4bb 100644 --- a/docs/user_related_apis_versioned/add-or-update-user-reading-session.api.mdx +++ b/docs/user_related_apis_versioned/add-or-update-user-reading-session.api.mdx @@ -5,7 +5,7 @@ description: "Create or update an existing reading session. Reading session is u sidebar_label: "Add or update user reading session" hide_title: true hide_table_of_contents: true -api: {"description":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","tags":["Reading Sessions"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chapterNumber":{"type":"integer","minimum":1,"description":"The Surah number to be added to reading session."},"verseNumber":{"type":"integer","minimum":1,"description":"The Ayah number to be added to reading session."}},"required":["chapterNumber","verseNumber"],"additionalProperties":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":["reading session created"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/reading-sessions/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"chapterNumber":0,"verseNumber":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 ## 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"},"postman":{"name":"Add or update user reading session","description":{"content":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","type":"text/plain"},"url":{"path":["v1","reading-sessions",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","tags":["Reading Sessions"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"chapterNumber":{"type":"integer","minimum":1,"description":"The Surah number to be added to reading session."},"verseNumber":{"type":"integer","minimum":1,"description":"The Ayah number to be added to reading session."}},"required":["chapterNumber","verseNumber"],"additionalProperties":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":["reading session created"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"chapterNumber":0,"verseNumber":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 ## 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"},"postman":{"name":"Add or update user reading session","description":{"content":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null diff --git a/docs/user_related_apis_versioned/add-update-activity-day.api.mdx b/docs/user_related_apis_versioned/add-update-activity-day.api.mdx index 548f21b5..6a80ec2e 100644 --- a/docs/user_related_apis_versioned/add-update-activity-day.api.mdx +++ b/docs/user_related_apis_versioned/add-update-activity-day.api.mdx @@ -5,7 +5,7 @@ description: "Add or update an activity day." sidebar_label: "Add/update activity day" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update an activity day.","tags":["Activity Days"],"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":"The date of the activity day, can be today or a past date. If not passed, default to today","example":"2023-09-01"},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The type of the activity day","example":"QURAN"}},"required":["type"],"additionalProperties":false,"oneOf":[{"type":"object","required":["seconds","ranges","mushafId"],"additionalProperties":false,"title":"QURAN"}]}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/activity-days/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"date":"2023-09-01","type":"QURAN","seconds":5,"ranges":["1:5-1:10"],"mushafId":4},"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 ## 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"},"postman":{"name":"Add/update activity day","description":{"content":"Add or update an activity day.","type":"text/plain"},"url":{"path":["v1","activity-days",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update an activity day.","tags":["Activity Days"],"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":"The date of the activity day, can be today or a past date. If not passed, default to today","example":"2023-09-01"},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The type of the activity day","example":"QURAN"}},"required":["type"],"additionalProperties":false,"oneOf":[{"type":"object","required":["seconds","ranges","mushafId"],"additionalProperties":false,"title":"QURAN"}]}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"date":"2023-09-01","type":"QURAN","seconds":5,"ranges":["1:5-1:10"],"mushafId":4},"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 ## 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"},"postman":{"name":"Add/update activity day","description":{"content":"Add or update an activity day.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null diff --git a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx index 61f4c2b9..b51ed093 100644 --- a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"post","path":"/v1/bookmarks/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Add a bookmark by details. -
                      Request Body
                        anyOf
                      +
                      Query Parameters
                      Request Body
                        anyOf
                      Request has been handled successfully. -
                      Schema
                        data object
                      +
                      Response Headers
                      • X-Mutation-At string
                        + +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
                        data object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx b/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx index 2c4ff822..99f36e98 100644 --- a/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx +++ b/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Add or update one or more user preferences groups like favorite Ta sidebar_label: "Bulk add or update preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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"}},"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale"],"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}},"additionalProperties":false,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"theme":{"type":"auto"},"reading":{"readingPreference":"translation","selectedWordByWordLocale":"en","wordClickFunctionality":"play-audio","isReadingByRevelationOrder":true,"wordByWordContentType":["translation"],"wordByWordDisplay":["tooltip"],"wordByWordTooltipContentType":["translation"],"wordByWordInlineContentType":[],"selectedReadingTranslation":"131"},"quranReaderStyles":{"tafsirFontScale":3,"quranTextFontScale":3,"translationFontScale":3,"wordByWordFontScale":3,"quranFont":"code_v1","mushafLines":"16_lines"},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"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,"quranFont":"code_v1","mushafLines":"16_lines"},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"},"userHasCustomised":{"userHasCustomised":false}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one or more user preferences groups like favorite Tafsirs and translations. -
                      Query Parameters
                      Request Body
                        theme object
                        reading object
                        quranReaderStyles object
                        = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>
                        translations object
                        tafsirs object
                        audio object
                        language object
                      +
                      Query Parameters
                      Request Body
                        theme object
                        reading object
                        = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
                        quranReaderStyles object
                        = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
                        translations object
                        tafsirs object
                        audio object
                        language object
                        userHasCustomised object
                      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/comments-controller-create.api.mdx index 7c31395b..5b914cf1 100644 --- a/docs/user_related_apis_versioned/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
                      Schema
                        comment object required
                        author object
                        avatarUrls object required
                        mentions object[]
                      • Array [
                        • avatarUrls object required
                      • ]
                        • tags object[]
                      • Array [
                      • ]
                      +
                      Schema
                        comment object required
                        author object
                        avatarUrls object required
                        mentions object[]
                      • Array [
                        • avatarUrls object required
                      • ]
                        • tags object[]
                      • Array [
                      • ]
                      Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/comments-controller-get.api.mdx index 330f08f6..43e8751b 100644 --- a/docs/user_related_apis_versioned/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
                      Schema
                        replies object[] required
                      • Array [
                        • author object
                        avatarUrls object required
                        mentions object[]
                      • Array [
                        • avatarUrls object required
                      • ]
                        • tags object[]
                      • Array [
                      • ]
                      • ]
                        • comment object required
                        author object
                        avatarUrls object required
                        mentions object[]
                      • Array [
                        • avatarUrls object required
                      • ]
                        • tags object[]
                      • Array [
                      • ]
                      +
                      Schema
                        replies object[] required
                      • Array [
                        • author object
                        avatarUrls object required
                        mentions object[]
                      • Array [
                        • avatarUrls object required
                      • ]
                        • tags object[]
                      • Array [
                      • ]
                      • ]
                        • comment object required
                        author object
                        avatarUrls object required
                        mentions object[]
                      • Array [
                        • avatarUrls object required
                      • ]
                        • tags object[]
                      • Array [
                      • ]
                      Parent comment not found diff --git a/docs/user_related_apis_versioned/create-a-goal.api.mdx b/docs/user_related_apis_versioned/create-a-goal.api.mdx index 9686e885..dfaae198 100644 --- a/docs/user_related_apis_versioned/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmkg2wee5000d2o5r2resd1lm"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
                      Schema
                        data object
                      +
                      Schema
                        data object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/delete-a-goal.api.mdx index dfb8e73b..d8996ea4 100644 --- a/docs/user_related_apis_versioned/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkg2wee5000d2o5r2resd1lm"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
                      Path Parameters
                      Query Parameters
                      Header Parameters
                      +
                      Path Parameters
                      Query Parameters
                      Header Parameters
                      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/delete-bookmark.api.mdx index a45b9984..75bcc9c8 100644 --- a/docs/user_related_apis_versioned/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkg2wdy700062o5r7kmica10"},"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}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkthm7rj0006r4jq3w04aolo"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
                      Path Parameters
                      +
                      Path Parameters
                      Query Parameters
                      Request has been handled successfully. -
                      Schema
                        data object
                      +
                      Response Headers
                      • X-Mutation-At string
                        + +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
                        data object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx index 819b1ab8..160ff0ac 100644 --- a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkg2we8q000a2o5rcu65crzk"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkg2we8q000b2o5r47opazrd"},"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}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7uu000ar4jqhzbcdlql"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkthm7uu000br4jqc2ec5h49"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
                      Path Parameters
                      +
                      Path Parameters
                      Query Parameters
                      Request has been handled successfully. -
                      Schema
                        data object
                      +
                      Response Headers
                      • X-Mutation-At string
                        + +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
                        data object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-collection.api.mdx b/docs/user_related_apis_versioned/delete-collection.api.mdx index 5beb75bd..24e668c7 100644 --- a/docs/user_related_apis_versioned/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkg2we8d00092o5r2jux9iov"},"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}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7up0009r4jqfaqg4iha"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
                      Path Parameters
                      +
                      Path Parameters
                      Query Parameters
                      Request has been handled successfully. -
                      Schema
                        data object
                      +
                      Response Headers
                      • X-Mutation-At string
                        + +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
                        data object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-note-by-id.api.mdx b/docs/user_related_apis_versioned/delete-note-by-id.api.mdx index 6233d25d..ee0b0a28 100644 --- a/docs/user_related_apis_versioned/delete-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/delete-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a note by its ID." sidebar_label: "Delete note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Delete a note by its ID. -
                      Path Parameters
                      +
                      Path Parameters
                      Query Parameters
                      Request has been handled successfully. -
                      Schema
                        data object
                      +
                      Response Headers
                      • X-Mutation-At string
                        + +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
                        data object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-activity-days.api.mdx b/docs/user_related_apis_versioned/get-activity-days.api.mdx index 7e4d7d7f..43df28b7 100644 --- a/docs/user_related_apis_versioned/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":"cmkg2wdks00042o5r0l5xfrpu"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
                      Query Parameters
                      +
                      Query Parameters
                      Request has been handled successfully. -
                      Schema
                        data object[]
                      • Array [
                        • ranges object
                        +
                        Schema
                          data object[]
                        • Array [
                          • ranges object
                          The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
                        • ]
                          • pagination object
                        +
                      • ]
                        • pagination object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx index 8eb9735e..7febad75 100644 --- a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
                      Query Parameters
                      +
                      Query Parameters
                      Request has been handled successfully. -
                      Schema
                        data object[]
                      • Array [
                      • ]
                        • pagination object
                      +
                      Schema
                        data object[]
                      • Array [
                      • ]
                        • pagination object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collections.api.mdx b/docs/user_related_apis_versioned/get-all-collections.api.mdx index a60e9b90..75560a7f 100644 --- a/docs/user_related_apis_versioned/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
                      Query Parameters
                      +
                      Query Parameters
                      Request has been handled successfully. -
                      Schema
                        data object[]
                      • Array [
                      • ]
                        • pagination object
                      +
                      Schema
                        data object[]
                      • Array [
                      • ]
                        • pagination object
                      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-notes.api.mdx b/docs/user_related_apis_versioned/get-all-notes.api.mdx index 6ea1992d..aec48f00 100644 --- a/docs/user_related_apis_versioned/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
                    • ]
                    • ]
                    pagination object
                  +
                • ]
                • ]
                pagination object
              The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx index d5188d00..b332d71d 100644 --- a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":"object","properties":{"id":{"type":"string","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
              Query Parameters
              +
              Query Parameters
              Request has been handled successfully. -
              Schema
                data object[]
              • Array [
              • ]
              +
              Schema
                data object[]
              • Array [
              • ]
              The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark.api.mdx b/docs/user_related_apis_versioned/get-bookmark.api.mdx index cf031d80..c57fb695 100644 --- a/docs/user_related_apis_versioned/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
              Schema
                data object
              +
              Schema
                data object
              The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx index b99dd858..7a745d72 100644 --- a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
              Schema
                data object[]
              • Array [
              • ]
                • pagination object
              +
              Schema
                data object[]
              • Array [
              • ]
                • pagination object
              The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx index f13e31f5..eba85733 100644 --- a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkg2weab000c2o5rbafhcreg"}},{"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkg2we2000072o5r6vqjgv4a"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkthm7vj000cr4jqdkfabg59"}},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
              Path Parameters
              Query Parameters
              +
              Path Parameters
              Query Parameters
              Request has been handled successfully. -
              Schema
                data object
                collection object
                bookmarks object[]
              • Array [
              • ]
                • pagination object
              +
              Schema
                data object
                collection object
                bookmarks object[]
              • Array [
              • ]
                • pagination object
              The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-mutations.api.mdx b/docs/user_related_apis_versioned/get-mutations.api.mdx new file mode 100644 index 00000000..5b282e98 --- /dev/null +++ b/docs/user_related_apis_versioned/get-mutations.api.mdx @@ -0,0 +1,86 @@ +--- +id: get-mutations +title: "Get mutations" +description: "Get list of mutations that were applied to resources after a certain point in time." +sidebar_label: "Get mutations" +hide_title: true +hide_table_of_contents: true +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +sidebar_class_name: "get api-method" +info_path: docs/user_related_apis_versioned/user-related-apis +custom_edit_url: null +--- + +import ApiTabs from "@theme/ApiTabs"; +import MimeTabs from "@theme/MimeTabs"; +import ParamsItem from "@theme/ParamsItem"; +import ResponseSamples from "@theme/ResponseSamples"; +import SchemaItem from "@theme/SchemaItem"; +import SchemaTabs from "@theme/SchemaTabs"; +import DiscriminatorTabs from "@theme/DiscriminatorTabs"; +import TabItem from "@theme/TabItem"; + +## Get mutations + + + +Get list of mutations that were applied to resources after a certain point in time. + +
              Query Parameters
              + +Request has been handled successfully. + +
              Schema
                data object
                + +Response schema for get mutations endpoint + +
                mutations object[]
                + +Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true. + +
              • Array [
                • data object
                + +The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. + +
              • ]
              + +The request is missing required parameters or is invalid. + +
              Schema
              + +The request is unauthorized. + +
              Schema
              + +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. + +
              Schema
              + +Not Found. The resource being accessed does not exist. + +
              Schema
              + +Validation Error. The request includes one or more invalid params. Please check the request params and try again. + +
              Schema
              + +Too many requests, please try again later. + +
              Schema
              + +Server Error. Something went wrong, try again later. + +
              Schema
              + +Invalid response from the upstream server + +
              Schema
              + +The server is currently unable to handle the request due to a temporary overload or scheduled maintenance + +
              Schema
              + +The server did not receive a timely response from the upstream server. + +
              Schema
              + \ No newline at end of file diff --git a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx index ffe69567..6809605b 100644 --- a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
            • ]
            • ]
            pagination object
          +
        • ]
      • ]
    pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-streaks.api.mdx b/docs/user_related_apis_versioned/get-streaks.api.mdx index 5b77900b..5633490d 100644 --- a/docs/user_related_apis_versioned/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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 streak.","example":"cmkg2wf48000f2o5r97huaiw5"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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 streak.","example":"cmkthm85f000fr4jq7l9khj0j"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx index 1ba2e9ec..ecabfd4c 100644 --- a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkg2wdks00042o5r0l5xfrpu"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx index 450c5ce8..2cec3820 100644 --- a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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":"object","properties":{"id":{"type":"string","example":"cmkg2wdxr00052o5rccy30b9g"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-preferences.api.mdx b/docs/user_related_apis_versioned/get-user-preferences.api.mdx index 65c7fd5a..1893c3b0 100644 --- a/docs/user_related_apis_versioned/get-user-preferences.api.mdx +++ b/docs/user_related_apis_versioned/get-user-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Get all user preferences like theme, favorite reciter, default lan sidebar_label: "Get user preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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"}},"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale"],"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}},"additionalProperties":false,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences",""],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all user preferences like theme, favorite reciter, default language etc. Request has been handled successfully. -
    Schema
      data object
      theme object
      reading object
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
    +
    Schema
      data object
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx index 5a0e9fc7..f4c2af65 100644 --- a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmkg2wdjn00002o5r5nq7hzfx"},"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":"cmkg2wdjo00012o5r8c8vabwk"},"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","example":"cmkg2wf2r000e2o5r1bkbcm8w"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkg2wdjp00022o5r9b7x3au2"},"endCursor":{"type":"string","example":"cmkg2wdjp00032o5rf27ce2l2"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm84w000er4jq7r9u47p2"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/posts-controller-create.api.mdx index 5e911853..e07b7088 100644 --- a/docs/user_related_apis_versioned/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-19T08:00:53.504Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:55.098Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx index ce3dd9fc..7ff34bba 100644 --- a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-19T08:00:53.504Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:55.098Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx index 69d0d5a7..9be873f4 100644 --- a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx index b16875b5..bfb42ed9 100644 --- a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx index 4cf50120..4f2ce7bb 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx index 388cf295..653286da 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx index fc48e22e..d979658f 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx index 2ed910f9..0fc40e36 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx index 7ea93bc3..0c2a6eb3 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/publish-note.api.mdx b/docs/user_related_apis_versioned/publish-note.api.mdx index 7dbf10ef..47447d78 100644 --- a/docs/user_related_apis_versioned/publish-note.api.mdx +++ b/docs/user_related_apis_versioned/publish-note.api.mdx @@ -5,7 +5,7 @@ description: "Publish a note to QR." sidebar_label: "Publish note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Publish a note to QR. -
    Path Parameters
    Request Body
      = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
    +
    Path Parameters
    Query Parameters
    Request Body
      = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
    Request has been handled successfully. -
    Schema
      data object
      +
      Response Headers
      • X-Mutation-At string
        + +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
        data object
        Response object indicating the success of the note publishing operation and the optional post ID if successful. diff --git a/docs/user_related_apis_versioned/sidebar.js b/docs/user_related_apis_versioned/sidebar.js index 524704a3..2be89f73 100644 --- a/docs/user_related_apis_versioned/sidebar.js +++ b/docs/user_related_apis_versioned/sidebar.js @@ -1 +1 @@ -module.exports = [{"type":"doc","id":"user_related_apis_versioned/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file +module.exports = [{"type":"doc","id":"user_related_apis_versioned/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-delete-account","label":"Delete user account permanently","className":"api-method delete"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Sync","items":[{"type":"doc","id":"user_related_apis_versioned/get-mutations","label":"Get mutations","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/sync-local-mutations","label":"Sync local mutations","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file diff --git a/docs/user_related_apis_versioned/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx new file mode 100644 index 00000000..45e80fd2 --- /dev/null +++ b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx @@ -0,0 +1,94 @@ +--- +id: sync-local-mutations +title: "Sync local mutations" +description: "An endpoint to sync local mutations to the server." +sidebar_label: "Sync local mutations" +hide_title: true +hide_table_of_contents: true +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +sidebar_class_name: "post api-method" +info_path: docs/user_related_apis_versioned/user-related-apis +custom_edit_url: null +--- + +import ApiTabs from "@theme/ApiTabs"; +import MimeTabs from "@theme/MimeTabs"; +import ParamsItem from "@theme/ParamsItem"; +import ResponseSamples from "@theme/ResponseSamples"; +import SchemaItem from "@theme/SchemaItem"; +import SchemaTabs from "@theme/SchemaTabs"; +import DiscriminatorTabs from "@theme/DiscriminatorTabs"; +import TabItem from "@theme/TabItem"; + +## Sync local mutations + + + +An endpoint to sync local mutations to the server. + +
        Query Parameters
        Request Body
          mutations object[] required
        • Array [
          • data object
          + +Resource data. Format depends on resource type. + +
        • ]
        + +Request has been handled successfully. + +
        Schema
          data object
          + +Response schema for post mutations endpoint + +
          mutations object[]
          + +Array of mutations that were successfully applied on the server. + +
        • Array [
          • data object
          + +The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. + +
        • ]
        + +The request is missing required parameters or is invalid. + +
        Schema
        + +The request is unauthorized. + +
        Schema
        + +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. + +
        Schema
        + +Not Found. The resource being accessed does not exist. + +
        Schema
        + +Out of Sync Error. The client lastMutationAt does not match server state. + +
        Schema
          error object
        + +Validation Error. The request includes one or more invalid params. + +
        Schema
          error object
        + +Too many requests, please try again later. + +
        Schema
        + +Server Error. Something went wrong, try again later. + +
        Schema
        + +Invalid response from the upstream server + +
        Schema
        + +The server is currently unable to handle the request due to a temporary overload or scheduled maintenance + +
        Schema
        + +The server did not receive a timely response from the upstream server. + +
        Schema
        + \ No newline at end of file diff --git a/docs/user_related_apis_versioned/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/tags-controller-find.api.mdx index 6e7d059e..150e9989 100644 --- a/docs/user_related_apis_versioned/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
        Schema
        • Array [
        • ]
        +
      Schema
      • Array [
      • ]
      \ No newline at end of file diff --git a/docs/user_related_apis_versioned/update-a-goal.api.mdx b/docs/user_related_apis_versioned/update-a-goal.api.mdx index 265f7835..00894220 100644 --- a/docs/user_related_apis_versioned/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkg2wee5000d2o5r2resd1lm"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        +
        Path Parameters
        Query Parameters
        Header Parameters
        Request Body
          amount object
          The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/docs/user_related_apis_versioned/update-collection.api.mdx b/docs/user_related_apis_versioned/update-collection.api.mdx index 32c449d5..95eaa6b4 100644 --- a/docs/user_related_apis_versioned/update-collection.api.mdx +++ b/docs/user_related_apis_versioned/update-collection.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing collection." sidebar_label: "Update collection" hide_title: true hide_table_of_contents: true -api: {"description":"Update an existing collection.","tags":["Collections"],"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."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update an existing collection.","tags":["Collections"],"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."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the collection to be updated."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Update an existing collection. -
          Path Parameters
          Request Body
          +
          Path Parameters
          Query Parameters
          Request Body
          Request has been handled successfully. -
          Schema
            data object
          +
          Response Headers
          • X-Mutation-At string
            + +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
            data object
          The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/update-note-by-id.api.mdx b/docs/user_related_apis_versioned/update-note-by-id.api.mdx index 64f89202..10bcfb2e 100644 --- a/docs/user_related_apis_versioned/update-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/update-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Update a note by its ID." sidebar_label: "Update note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,15 @@ import TabItem from "@theme/TabItem"; Update a note by its ID. -
          Path Parameters
          Request Body
            = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
          +
          Path Parameters
          Query Parameters
          Request Body
            = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
          Request has been handled successfully. -
          Schema
            data object
            = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
            attachedEntities object[]
            +
            Response Headers
            • X-Mutation-At string
              + +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
              data object
              = 6 characters` and `<= 10000 characters`"} schema={{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."}}>
              attachedEntities object[]
              An array of attached entities associated with the note. diff --git a/openAPI/user-related-apis/v1.json b/openAPI/user-related-apis/v1.json index eb02a60b..dc6f6e38 100644 --- a/openAPI/user-related-apis/v1.json +++ b/openAPI/user-related-apis/v1.json @@ -1 +1,17132 @@ -{"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 ## 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"},"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":{"Bookmark":{"type":"object","properties":{"id":{"type":"string","example":"cmktb9xqr00055w455mi6chpp"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false},"Collection":{"type":"object","properties":{"id":{"type":"string","example":"cmktb9xux00075w45cmsj1u3v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"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:10"},{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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":"cmktb9yuz000e5w45623a6qif"},"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"},"photoUrl":{"type":"string","example":"https://photos.quran.com/img/muhajir.jpg"}},"additionalProperties":false},"EditProfileDto":{"type":"object","properties":{"languageId":{"type":"number"},"reflectionLanguages":{"type":"array","items":{"type":"string"}},"ayahLanguages":{"type":"array","items":{"type":"string"}},"customized":{"type":"boolean"}}},"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"}},"createdAt":{"type":"object","example":"2000-01-21 00:00:00"},"joiningYear":{"type":"number","example":2025},"isPasswordSet":{"type":"boolean","example":true},"settings":{"type":"object","properties":{"ayahLanguages":{"required":false,"type":"array","items":{"type":"number"}},"reflectionLanguages":{"required":false,"type":"array","items":{"type":"number"}}}},"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},"averageToxicity":{"type":"number","default":0},"languageId":{"type":"number"},"banned":{"type":"boolean","default":false},"memberType":{"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","createdAt","joiningYear","settings","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"]},"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"]},"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/UserSerializedDto"}}},"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"}}},"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}},"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},"name":{"type":"string"},"description":{"type":"string"},"organizationWebsite":{"type":"string"},"country":{"type":"string"},"url":{"type":"string"}},"required":["id"]},"InviteUserDto":{"type":"object","properties":{"userIds":{"type":"array","items":{"type":"string"}},"emails":{"type":"array","items":{"type":"string"}}},"required":["userIds","emails"]},"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"}},"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"}},"required":["name","url"]},"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"]},"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"},"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"]},"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":{"post":{"$ref":"#/components/schemas/PostSerialized"},"success":{"type":"boolean"}},"required":["post","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","default":""}},"required":["abuse","comments"]},"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"}},"required":["name"],"additionalProperties":false}}}},"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}}}},"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}}}}}},"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":"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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/collections/{collectionId}/bookmarks":{"post":{"description":"Add a bookmark to an existing collection.","tags":["Collections"],"summary":"Add collection Bookmark","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmktb9xzo00085w451oje54n4"},"required":true,"description":"The Id of the collection to be added."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"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},"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","example":4}},"required":["key","verseNumber","mushaf"],"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"},"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","example":4}},"required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}}},"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}}}}}}},"/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":"cmktb9xzz00095w456lbc1qi4"},"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}}}},"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}}}}}},"get":{"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"summary":"Get collection items by id","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmktb9y2d000c5w45g6qr90jb"}},{"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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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/Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}},"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."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/collections/{collectionId}/bookmarks/{bookmarkId}":{"delete":{"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"summary":"Delete collection bookmark by id","parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktb9y08000a5w45cu2o4nfs"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmktb9y08000b5w457wnw9kgm"},"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}}}},"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}}}}}}},"/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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/bookmarks":{"post":{"description":"Add a bookmark by details.","tags":["Bookmarks"],"summary":"Add user bookmark","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"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},"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","example":4}},"required":["key","verseNumber","mushaf"],"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"},"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","example":4}},"required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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}}}},"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}}}}}},"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":"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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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/Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/bookmarks/{bookmarkId}":{"delete":{"description":"Delete a bookmark by id.","tags":["Bookmarks"],"summary":"Delete Bookmark","parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmktb9xra00065w4579sl6amp"},"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}}}},"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}}}}}}},"/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/Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/bookmarks/bookmark":{"get":{"description":"Get a bookmark by details","tags":["Bookmarks"],"summary":"Get bookmark","parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":{"$ref":"#/components/schemas/Bookmark"}},"additionalProperties":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}}}}}}},"/v1/bookmarks/collections":{"get":{"description":"Get all collections that a bookmark belongs to by bookmark details.","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":"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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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/Collection"}}},"additionalProperties":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}}}}}}},"/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,"anyOf":[{"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","quranFont","mushafLines"]}},"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}]}}}},"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}}}},"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}}}}}},"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}}}},"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}}}}}}},"/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"}}}},"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}}}},"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}}}}}}},"/v1/reading-sessions":{"post":{"description":"Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.","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 to be added to reading session."},"verseNumber":{"type":"integer","minimum":1,"description":"The Ayah number to be added to reading session."}},"required":["chapterNumber","verseNumber"],"additionalProperties":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":["reading session created"]}},"additionalProperties":false}},"additionalProperties":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}}}}}},"get":{"description":"Get all existing reading sessions.","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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/goals/get-todays-plan":{"get":{"description":"Get today's goal plan.","tags":["Goals"],"summary":"Get today's goal plan","parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmktb9xea00045w455e7yhgbd"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}}}},"/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":"cmktb9y5d000d5w45fcss1tsz"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}}},"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":"cmktb9y5d000d5w45fcss1tsz"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}}}},"/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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmktb9y5d000d5w45fcss1tsz"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}}}},"/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"],"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:10","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}}}},"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}}}}}}},"/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-31"},"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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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 streak.","example":"cmktb9yws000f5w450ra1201k"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/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":"array","items":{"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}}}},"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}}}}}}},"/v1/activity-days":{"post":{"description":"Add or update an activity day.","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":"The date of the activity day, can be today or a past date. If not passed, default to today","example":"2023-09-01"},"type":{"type":"string","enum":["QURAN","LESSON","QURAN_READING_PROGRAM"],"description":"The type of the activity day","example":"QURAN"}},"required":["type"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"seconds":{"type":"integer","minimum":1,"description":"Seconds spent reading the current request's 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":"Current request's read range of Ayahs","example":["1:5-1:10"]},"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"}]}}}},"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}}}},"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}}}}}},"get":{"description":"Get user activity days.","tags":["Activity Days"],"summary":"Get activity days","parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmktb9xcr00005w45etducc95"},"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":"cmktb9xcs00015w453dbw0ytg"},"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":"cmktb9xea00045w455e7yhgbd"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/activity-days/estimate-reading-time":{"get":{"description":"Estimate the number of seconds it would take to read a range. We estimate it based on the average reading speed we have collected 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}}}},"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}}}}}}},"/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":{"required":true,"description":"Settings fields to update - only include fields you want to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditProfileDto"}}}},"responses":{"200":{"description":"Settings updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid settings data"},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]},"get":{"operationId":"UsersController_profile","summary":"Get user profile","description":"Retrieve the complete profile of the authenticated user including personal info, settings, statistics, and connected accounts.","parameters":[{"name":"qdc","required":false,"in":"query","description":"Include Quran.com (QDC) connected account data","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Full user profile with all data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSerializedDto"}}}},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]},"put":{"operationId":"UsersController_updateProfile","summary":"Update user profile","description":"Update user profile information including name, bio, username, avatar, and social links. Validates username uniqueness.","parameters":[],"requestBody":{"required":true,"description":"Profile fields to update wrapped in a user object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProfileBodyDto"}}}},"responses":{"200":{"description":"Profile updated and returned with new values","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSerializedDto"}}}},"400":{"description":"Invalid profile data or username taken"},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/notes":{"get":{"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","summary":"Get all notes","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}},"post":{"tags":["Notes"],"description":"Add a new note.","summary":"Add note","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/notes/by-verse/:verseKey":{"get":{"tags":["Notes"],"description":"Retrieve notes by a specific verse.","summary":"Get notes by verse","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktb9xcs00025w45enboexlx"},"endCursor":{"type":"string","example":"cmktb9xcs00035w453htrdeb5"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/notes/by-attached-entity":{"get":{"tags":["Notes"],"description":"Retrieve notes by attached entity.","summary":"Get notes by attached entity","parameters":[{"in":"query","name":"entityId","schema":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"required":true,"description":"The unique identifier for the attached entity."},{"in":"query","name":"entityType","schema":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"required":true,"description":"The type of the attached entity, must be one of the predefined NoteEntityType values."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}}},"additionalProperties":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}}}}}}},"/v1/notes/count-within-range":{"get":{"tags":["Notes"],"description":"Get the count of notes within a range of verses.","summary":"Get notes count within verse range","parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The starting verse key of the range.","example":"2:12"},"required":true,"description":"The starting verse key of the range."},{"in":"query","name":"to","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The ending verse key of the range.","example":"2:18"},"required":true,"description":"The ending verse key of the range."}],"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":{"type":"integer","minimum":1},"description":"A map of verse keys to note counts, where each key is a verse key and each value is an integer count of notes.","example":{"1:2":5,"1:3":1,"1:4":1}}},"additionalProperties":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}}}}}}},"/v1/notes/by-range":{"get":{"tags":["Notes"],"description":"Retrieve notes by a range of verses.","summary":"Get notes by verse range","parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The starting verse key of the range.","example":"2:12"},"required":true,"description":"The starting verse key of the range."},{"in":"query","name":"to","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The ending verse key of the range.","example":"2:18"},"required":true,"description":"The ending verse key of the range."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}}},"additionalProperties":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}}}}}}},"/v1/notes/:noteId":{"get":{"tags":["Notes"],"description":"Retrieve a note by its ID.","summary":"Get note by ID","parameters":[{"in":"query","name":"withAttachedEntities","schema":{"type":"boolean","description":"Specifies whether to include attached entities in the response, defaults to true.","example":true,"default":true},"description":"Specifies whether to include attached entities in the response, defaults to true."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":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}}}}}},"patch":{"tags":["Notes"],"description":"Update a note by its ID.","summary":"Update note by ID","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":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}}}}}},"delete":{"tags":["Notes"],"description":"Delete a note by its ID.","summary":"Delete note by ID","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":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}}}}}}},"/v1/notes/:noteId/publish":{"post":{"tags":["Notes"],"description":"Publish a note to QR.","summary":"Publish note","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":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}}}}}}},"/v1/users/my-rooms":{"get":{"operationId":"UsersController_rooms","summary":"Get logged-in user rooms","description":"Retrieve all rooms (groups and pages) the authenticated user is a member of. Supports filtering by name and pagination.","parameters":[{"name":"name","required":false,"in":"query","description":"Filter rooms by name","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Rooms per page (default: 10)","schema":{"type":"number"}}],"responses":{"200":{"description":"User rooms with pagination metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserRoomsResponse"}}}},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users/search":{"get":{"operationId":"UsersController_search","summary":"Search for users","description":"Search users by name or username. Supports mentioning in posts, finding users for room invites, and general discovery. Results can be scoped to specific contexts.","parameters":[{"name":"query","required":false,"in":"query","description":"Search term for name/username","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Results per page (default: 10)","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"all","required":false,"in":"query","description":"Search all users (not just followed)","schema":{"type":"boolean"}},{"name":"postingAs","required":false,"in":"query","description":"Filter for posting-as feature","schema":{"type":"boolean"}},{"name":"postingAsUserId","required":false,"in":"query","description":"User ID for posting-as context","schema":{"type":"string"}},{"name":"roomId","required":false,"in":"query","description":"Room ID for scoped search","schema":{"type":"number"}}],"responses":{"200":{"description":"Matching users with pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsersSearchResponse"}}}}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users/{followeeId}/toggle-follow":{"post":{"operationId":"UsersController_toggleFollow","summary":"Toggle follow/unfollow a user","description":"Follow or unfollow another user. When following, their posts will appear in your FOLLOWING feed. Can optionally specify action to force follow/unfollow.","parameters":[{"name":"followeeId","required":true,"in":"path","description":"UUID of the user to follow/unfollow","schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Optional: specify \"follow\" or \"unfollow\" action explicitly","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToggleFollowDto"}}}},"responses":{"200":{"description":"Follow status changed - returns new state","content":{"application/json":{"schema":{"type":"object","properties":{"followed":{"type":"boolean","description":"true if now following"}}}}}},"400":{"description":"Cannot follow yourself or action already in desired state"},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users/{followerId}/remove-follower":{"post":{"operationId":"UsersController_removeFollower","summary":"Remove a follower","description":"Remove a user from your followers list. They will no longer see you as followed and won't receive notifications about your activity.","parameters":[{"name":"followerId","required":true,"in":"path","description":"UUID of the follower to remove","schema":{"type":"string"}}],"responses":{"200":{"description":"Follower removed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"},"404":{"description":"Follower relationship not found"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users/{id}":{"get":{"operationId":"UsersController_getUserProfile","summary":"Get user profile by id or username","description":"Retrieve a user profile by either UUID or username. If viewing your own profile, returns full data; otherwise returns public profile with follow relationship status.","parameters":[{"name":"id","required":false,"in":"path","description":"UUID of the user","schema":{"type":"string"}},{"name":"username","required":false,"in":"path","description":"Username of the user (case-insensitive)","schema":{"type":"string"}},{"name":"qdc","required":false,"in":"query","description":"Include Quran.com connected account data","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Own profile with full data including settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSerializedDto"}}}},"404":{"description":"User not found"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users/{username}/profile":{"get":{"operationId":"UsersController_getUserProfile","summary":"Get user profile by id or username","description":"Retrieve a user profile by either UUID or username. If viewing your own profile, returns full data; otherwise returns public profile with follow relationship status.","parameters":[{"name":"id","required":false,"in":"path","description":"UUID of the user","schema":{"type":"string"}},{"name":"username","required":false,"in":"path","description":"Username of the user (case-insensitive)","schema":{"type":"string"}},{"name":"qdc","required":false,"in":"query","description":"Include Quran.com connected account data","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Own profile with full data including settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserSerializedDto"}}}},"404":{"description":"User not found"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users/{id}/followers":{"get":{"operationId":"UsersController_getUserFollowers","summary":"Get user followers","description":"Retrieve a paginated list of users who follow the specified user. Includes follow relationship to the viewer if authenticated.","parameters":[{"name":"id","required":true,"in":"path","description":"UUID of the user","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Results per page (default: 10)","schema":{"minimum":1,"maximum":20,"default":20,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}}],"responses":{"200":{"description":"List of followers with pagination"},"404":{"description":"User not found"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users/{id}/following":{"get":{"operationId":"UsersController_getUserFollowing","summary":"Get users followed by user","description":"Retrieve a paginated list of users that the specified user follows. Includes follow relationship to the viewer if authenticated.","parameters":[{"name":"id","required":true,"in":"path","description":"UUID of the user","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Results per page (default: 10)","schema":{"minimum":1,"maximum":20,"default":20,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}}],"responses":{"200":{"description":"List of followed users with pagination"},"404":{"description":"User not found"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/users":{"delete":{"operationId":"UsersController_deleteAccount","summary":"Delete user account permanently","description":"Permanently delete the authenticated user account and all associated data from QuranReflect and Quran.com. This action is irreversible. The user is immediately banned to prevent further actions, then all data is deleted in the background. All posts, comments, likes, preferences, and memberships will be removed. If the user owns rooms, posts by other members will be converted to global posts.","parameters":[],"responses":{"200":{"description":"Account deletion initiated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Account deletion initiated successfully"}}}}}},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/admins-access":{"post":{"operationId":"RoomsController_adminsAccess","summary":"Update room admin access","description":"Grant or revoke admin privileges for a user in a room. Only room owners or existing admins can modify admin access.","parameters":[],"requestBody":{"required":true,"description":"Contains roomId, userId, and admin boolean to grant/revoke access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomAdminUpdateDto"}}}},"responses":{"200":{"description":"Admin access updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to modify admin access"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/groups":{"patch":{"operationId":"RoomsController_updateGroup","summary":"Update a group","description":"Update group properties like name, description, URL, avatar, country, or public visibility. Only group admins/owners can update.","parameters":[],"requestBody":{"required":true,"description":"Group fields to update - all fields optional except id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateGroupDto"}}}},"responses":{"200":{"description":"Group updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"room":{"type":"object"}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to update this group"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]},"post":{"operationId":"RoomsController_createNewGroup","summary":"Create a new group","description":"Create a new community group for sharing reflections. Groups can be public or private, and the creator becomes the owner.","parameters":[],"requestBody":{"required":true,"description":"Group creation details including name, description, URL, and visibility","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateGroupDto"}}}},"responses":{"201":{"description":"Group created successfully"},"400":{"description":"Invalid group data or URL already taken"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/pages":{"patch":{"operationId":"RoomsController_updatePage","summary":"Update a page","description":"Update page properties like name, description, contact info, organization details, or visibility. Only page admins/owners can update.","parameters":[],"requestBody":{"required":true,"description":"Page fields to update - all fields optional except id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePageDto"}}}},"responses":{"200":{"description":"Page updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"room":{"type":"object"}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to update this page"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]},"post":{"operationId":"RoomsController_createNewPage","summary":"Create a new page","description":"Submit a request to create a new organizational page. Pages require admin approval and include organization details, contact info, and purpose statement.","parameters":[],"requestBody":{"required":true,"description":"Page creation details including name, description, URL, organization info, and purpose","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePageDto"}}}},"responses":{"201":{"description":"Page request submitted for admin review","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object"},"message":{"type":"string"}}}}}},"400":{"description":"Invalid page data or URL already taken"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{id}/members":{"get":{"operationId":"RoomsController_getRoomMembers","summary":"Get room members","description":"Retrieve paginated list of members in a room (group or page). Returns user profiles with their roles.","parameters":[{"name":"limit","required":false,"in":"query","description":"Members per page (default: 10)","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"id","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Room members retrieved with pagination"},"404":{"description":"Room not found"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{id}/invite":{"post":{"operationId":"RoomsController_inviteUserToRoom","summary":"Invite user to room","description":"Send an invitation to a user to join the room. User will receive a notification/email with an invite link. Only admins can invite.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"User identification for invitation (email or userId)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteUserDto"}}}},"responses":{"200":{"description":"Invitation sent successfully"},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to invite members"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{id}/accept-invite":{"get":{"operationId":"RoomsController_acceptInvite","summary":"Accept room invite","description":"Accept an invitation to join a room using the token from the invite link. Adds user as member.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}},{"name":"token","required":true,"in":"query","description":"Invitation token from invite link","schema":{"type":"string"}}],"responses":{"200":{"description":"Invitation accepted - user is now a member"},"400":{"description":"Invalid or expired token"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{id}/reject-invite":{"get":{"operationId":"RoomsController_rejectInvite","summary":"Reject room invite","description":"Decline an invitation to join a room. Invalidates the invite token.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}},{"name":"token","required":true,"in":"query","description":"Invitation token from invite link","schema":{"type":"string"}}],"responses":{"200":{"description":"Invitation rejected"},"400":{"description":"Invalid or expired token"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{id}/members/{userId}":{"delete":{"operationId":"RoomsController_removeMember","summary":"Remove member from room","description":"Remove a user from a room (group or page). Only admins can remove other members. Users can remove themselves.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}},{"name":"userId","required":true,"in":"path","description":"UUID of the user to remove","schema":{"type":"string"}}],"responses":{"200":{"description":"Member removed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to remove this member"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/joined-rooms":{"get":{"operationId":"RoomsController_getRooms","summary":"Get joined or managed rooms","description":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","parameters":[{"name":"query","required":false,"in":"query","description":"Search query for room names","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Rooms per page (default: 5)","schema":{"minimum":1,"maximum":5,"default":5,"type":"number"}}],"responses":{"200":{"description":"Rooms retrieved with pagination"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/managed-rooms":{"get":{"operationId":"RoomsController_getRooms","summary":"Get joined or managed rooms","description":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","parameters":[{"name":"query","required":false,"in":"query","description":"Search query for room names","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Rooms per page (default: 5)","schema":{"minimum":1,"maximum":5,"default":5,"type":"number"}}],"responses":{"200":{"description":"Rooms retrieved with pagination"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/search":{"get":{"operationId":"RoomsController_searchRooms","summary":"Search rooms","description":"Search for public groups and pages by name or description. Results can be filtered by room type.","parameters":[{"name":"query","required":false,"in":"query","description":"Search term for room name/description","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Results per page (default: 10)","schema":{"type":"number"}},{"name":"roomType","required":false,"in":"query","description":"Filter by room type: GROUP or PAGE","schema":{"type":"string"}}],"responses":{"200":{"description":"Matching rooms with pagination"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/group/{url}":{"get":{"operationId":"RoomsController_getRoomProfile","summary":"Get room profile by URL or subdomain","description":"Retrieve a room profile by its unique URL (for groups) or subdomain (for pages). Returns room details, member counts, and relationship status.","parameters":[{"name":"url","required":false,"in":"path","description":"Group URL identifier (lowercase)","schema":{"type":"string"}},{"name":"subdomain","required":false,"in":"path","description":"Page subdomain identifier (lowercase)","schema":{"type":"string"}}],"responses":{"200":{"description":"Room profile with details and membership info"},"404":{"description":"Room not found"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/page/{subdomain}":{"get":{"operationId":"RoomsController_getRoomProfile","summary":"Get room profile by URL or subdomain","description":"Retrieve a room profile by its unique URL (for groups) or subdomain (for pages). Returns room details, member counts, and relationship status.","parameters":[{"name":"url","required":false,"in":"path","description":"Group URL identifier (lowercase)","schema":{"type":"string"}},{"name":"subdomain","required":false,"in":"path","description":"Page subdomain identifier (lowercase)","schema":{"type":"string"}}],"responses":{"200":{"description":"Room profile with details and membership info"},"404":{"description":"Room not found"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/group/{url}/accept/{token}":{"get":{"operationId":"RoomsController_acceptByPrivateToken","summary":"Accept room invite by private token","description":"Accept an invitation using a private room URL with embedded token. Alternative to the /accept-invite endpoint for direct link access.","parameters":[{"name":"url","required":false,"in":"path","description":"Group URL identifier","schema":{"type":"string"}},{"name":"subdomain","required":false,"in":"path","description":"Page subdomain identifier","schema":{"type":"string"}},{"name":"token","required":true,"in":"path","description":"Private invitation token","schema":{"type":"string"}}],"responses":{"200":{"description":"Invitation accepted - user added to room"},"400":{"description":"Invalid or expired token"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/page/{subdomain}/accept/{token}":{"get":{"operationId":"RoomsController_acceptByPrivateToken","summary":"Accept room invite by private token","description":"Accept an invitation using a private room URL with embedded token. Alternative to the /accept-invite endpoint for direct link access.","parameters":[{"name":"url","required":false,"in":"path","description":"Group URL identifier","schema":{"type":"string"}},{"name":"subdomain","required":false,"in":"path","description":"Page subdomain identifier","schema":{"type":"string"}},{"name":"token","required":true,"in":"path","description":"Private invitation token","schema":{"type":"string"}}],"responses":{"200":{"description":"Invitation accepted - user added to room"},"400":{"description":"Invalid or expired token"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{id}":{"get":{"operationId":"RoomsController_getRoomProfileById","summary":"Get room profile by ID","description":"Retrieve a room profile by its unique numeric ID. Returns room details, member counts, and relationship status for the current user.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Room profile retrieved successfully"},"404":{"description":"Room not found"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{id}/posts":{"get":{"operationId":"RoomsController_getRoomPosts","summary":"Get room posts","description":"Retrieve paginated posts shared within a room. Supports filtering by tab (REFLECTIONS, DISCUSSIONS) and sorting (LATEST, POPULAR).","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Sort order (default: latest)","schema":{"enum":["latest","popular"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Posts per page (max: 20)","schema":{"minimum":1,"maximum":20,"default":20,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"tab","required":false,"in":"query","description":"Filter posts by content type","schema":{"enum":["reflections","saved","public","members_only"],"type":"string"}}],"responses":{"200":{"description":"Room posts with pagination"},"404":{"description":"Room not found"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{groupId}/join":{"post":{"operationId":"RoomsController_joinRoom","summary":"Join a group","description":"Join a public group as a member. For private groups, an invitation is required. Returns whether the join was successful.","parameters":[{"name":"groupId","required":true,"in":"path","description":"Unique numeric group ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully joined the group","content":{"application/json":{"schema":{"type":"object","properties":{"joined":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"Group is private - invitation required"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{groupId}/leave":{"post":{"operationId":"RoomsController_leaveGroup","summary":"Leave a group","description":"Leave a group the user is currently a member of. Owners cannot leave - they must transfer ownership first.","parameters":[{"name":"groupId","required":true,"in":"path","description":"Unique numeric group ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully left the group","content":{"application/json":{"schema":{"type":"object","properties":{"left":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"Owner cannot leave - transfer ownership first"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{pageId}/follow":{"post":{"operationId":"RoomsController_followPage","summary":"Follow a page","description":"Follow an organizational page to see their posts in your feed. Pages represent verified organizations or scholars.","parameters":[{"name":"pageId","required":true,"in":"path","description":"Unique numeric page ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully followed the page","content":{"application/json":{"schema":{"type":"object","properties":{"followed":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{pageId}/unfollow":{"post":{"operationId":"RoomsController_unfollowPage","summary":"Unfollow a page","description":"Stop following a page. Their posts will no longer appear in your personalized feed.","parameters":[{"name":"pageId","required":true,"in":"path","description":"Unique numeric page ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Successfully unfollowed the page","content":{"application/json":{"schema":{"type":"object","properties":{"unfollowed":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/rooms/{roomId}/posts/{postId}/privacy":{"patch":{"operationId":"RoomsController_updatePostPrivacy","summary":"Update post privacy in room","description":"Change the visibility of a post within a room. Toggle between public (visible outside room) and private (members only). Only admins can modify.","parameters":[{"name":"roomId","required":true,"in":"path","description":"Unique numeric room ID","schema":{"type":"number"}},{"name":"postId","required":true,"in":"path","description":"Unique numeric post ID","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Privacy setting with isPublic boolean","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoomPostUpdatePrivacyDto"}}}},"responses":{"200":{"description":"Post privacy updated successfully"},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to modify post privacy"},"404":{"description":"Room or post not found"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/feed":{"get":{"operationId":"PostsController_feed","summary":"Get posts feed","description":"Retrieve a paginated feed of posts (reflections). Supports filtering by authors, tags, Quran references, groups, pages, and post types. Results can be filtered by language preferences from user settings or query parameters.","parameters":[{"name":"tab","required":false,"in":"query","description":"Feed tab type. feed shows personalized content, trending shows explore, following shows posts from followed users.","schema":{"enum":["newest","latest","following","draft","favorite","most_popular","only_room_members","public","feed","trending","popular"],"type":"string"}},{"name":"languages","required":false,"in":"query","description":"Array of language IDs to filter posts by reflection language","schema":{"type":"array","items":{"type":"number"}}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of posts per page (default: 20)","schema":{"minimum":1,"default":20,"type":"number"}},{"required":false,"name":"authors","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"required":false,"name":"tags","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"required":false,"name":"references","in":"query","schema":{"type":"array","items":{"$ref":"#/components/schemas/ReferenceAttributes"}}},{"required":false,"name":"groups","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"required":false,"name":"pages","in":"query","schema":{"type":"array","items":{"type":"string"}}},{"required":false,"name":"postTypeIds","in":"query","schema":{"type":"array","items":{"type":"number"}}},{"required":false,"name":"tagsOperator","in":"query","schema":{"enum":["OR","AND"],"type":"string"}},{"required":false,"name":"referencesOperator","in":"query","schema":{"enum":["OR","AND"],"type":"string"}},{"required":false,"name":"verifiedOnly","in":"query","schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"description":"Feed retrieved successfully with paginated posts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedResponseDto"}}}}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/my-posts":{"get":{"operationId":"PostsController_getLoggedinUserPosts","summary":"Get current user posts","description":"Retrieve posts created by the currently authenticated user. Supports filtering by tab (MY_REFLECTIONS, SAVED, DRAFTS), sorting options, and post type filtering.","parameters":[{"name":"tab","required":false,"in":"query","description":"Profile tab filter (default: my_reflections)","schema":{"enum":["my_reflections","saved","notes","mentions"],"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort order for posts (default: latest)","schema":{"enum":["latest","popular"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of posts per page (default: 20, max: 20)","schema":{"minimum":1,"maximum":20,"default":20,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"postTypeIds","required":false,"in":"query","description":"Array of post type IDs to filter by","schema":{"type":"array","items":{"type":"number"}}}],"responses":{"200":{"description":"User posts retrieved successfully with pagination metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedResponseDto"}}}},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/{id}":{"get":{"operationId":"PostsController_findOne","summary":"Get post by ID","description":"Retrieve a specific post by its unique numeric ID. Returns the full post with author details, tags, references, room information, and engagement metrics. Admins can view additional moderation details.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Post found and returned with all associated data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostSerialized"}}}},"404":{"description":"Post not found or has been deleted"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]},"delete":{"operationId":"PostsController_delete","summary":"Delete post","description":"Soft-delete a post by marking it as removed. Only the post author or admins can delete posts. Related engagement counts (likes, comments, saves) update asynchronously via background jobs, so metrics may briefly lag.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to delete","schema":{"type":"number"}}],"responses":{"200":{"description":"Post deletion accepted and queued for processing","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to delete this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]},"patch":{"operationId":"PostsController_edit","summary":"Edit post","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/viewed/{id}":{"get":{"operationId":"PostsController_viewTracking","summary":"Track post view","description":"Record that a post has been viewed by the current user (if authenticated). Used for analytics and engagement tracking. Does not require authentication but will track user-specific views when logged in.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID","schema":{"type":"number"}}],"responses":{"200":{"description":"View tracked successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts":{"post":{"operationId":"PostsController_create","summary":"Create post","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/{id}/report":{"post":{"operationId":"PostsController_reportAbuse","summary":"Report post abuse","description":"Report a post for moderation review. Provide a reason for the report to help moderators evaluate the content. Multiple reports on the same post may trigger automatic review.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to report","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Report details including reason for flagging the content","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportAbuseBodyDto"}}}},"responses":{"200":{"description":"Report submitted successfully for moderation review","content":{"application/json":{"schema":{"type":"object","properties":{"reported":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/user-posts/{id}":{"get":{"operationId":"PostsController_getUserPost","summary":"Get user posts","description":"Retrieve public posts created by a specific user. If viewing own posts while authenticated, returns all posts including drafts. Supports sorting and filtering by post type.","parameters":[{"name":"id","required":true,"in":"path","description":"UUID of the user whose posts to retrieve","schema":{"type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort order for posts (default: latest)","schema":{"enum":["latest","popular"],"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of posts per page (default: 20, max: 20)","schema":{"minimum":1,"maximum":20,"default":20,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number for pagination (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"postTypeIds","required":false,"in":"query","description":"Array of post type IDs to filter by","schema":{"type":"array","items":{"type":"number"}}}],"responses":{"200":{"description":"User posts retrieved with pagination metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedResponseDto"}}}}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/{id}/toggle-like":{"post":{"operationId":"PostsController_toggleLike","summary":"Toggle post like","description":"Toggle like status for a post. If already liked, removes the like. If not liked, adds a like. Updates the post like count and triggers notifications.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to like/unlike","schema":{"type":"number"}}],"responses":{"200":{"description":"Like status toggled - returns new state","content":{"application/json":{"schema":{"type":"object","properties":{"liked":{"type":"boolean","description":"true if now liked, false if now unliked"}}}}}},"401":{"description":"User not authenticated"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/{id}/toggle-save":{"post":{"operationId":"PostsController_toggleSave","summary":"Toggle post save","description":"Toggle save/bookmark status for a post. Saved posts appear in the SAVED tab of the user profile for easy access later.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to save/unsave","schema":{"type":"number"}}],"responses":{"200":{"description":"Save status toggled - returns new state","content":{"application/json":{"schema":{"type":"object","properties":{"saved":{"type":"boolean","description":"true if now saved, false if now unsaved"}}}}}},"401":{"description":"User not authenticated"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/{id}/comments":{"get":{"operationId":"PostsController_getComments","summary":"Get post comments","description":"Retrieve paginated top-level comments for a post. Use the replies endpoint to get nested replies for specific comments.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"minimum":1,"maximum":20,"default":20,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"minimum":1,"default":1,"type":"number"}}],"responses":{"200":{"description":"Comments retrieved with pagination metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostCommentsResponse"}}}},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/{id}/all-comments":{"get":{"operationId":"PostsController_getAllComment","summary":"Get all post comments","description":"Retrieve all comments for a post in a single request without pagination. Useful for displaying full comment threads or export scenarios.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID","schema":{"type":"number"}}],"responses":{"200":{"description":"All comments returned with total count","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostAllCommentsResponse"}}}},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/export/pdf":{"post":{"operationId":"PostsController_exportMultiplePosts","summary":"Export posts as PDF","description":"Generate a downloadable PDF document containing selected posts with their full content, Quran references, and author information. Ayah translations are rendered according to user language preferences.","parameters":[],"requestBody":{"required":true,"description":"Array of post IDs to include in the PDF export (minimum 1)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportPostsDto"}}}},"responses":{"200":{"description":"PDF file generated and returned as binary attachment","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Invalid request - empty or invalid post IDs array"},"401":{"description":"User not authenticated"},"404":{"description":"No accessible posts found for the given IDs"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/count-within-range":{"get":{"operationId":"PostsController_getMyPostsCountWithinRange","summary":"Get posts count within range","description":"Count how many posts the current user has written for verses within a specified Quran verse range. Useful for reading goals and progress tracking.","parameters":[{"name":"from","required":true,"in":"query","description":"Start verse key in format chapter:verse (e.g., \"2:1\")","schema":{"pattern":"VERSE_KEY_REGEX","example":"2:1","type":"string"}},{"name":"to","required":true,"in":"query","description":"End verse key in format chapter:verse (e.g., \"2:286\")","schema":{"pattern":"VERSE_KEY_REGEX","example":"2:286","type":"string"}}],"responses":{"200":{"description":"Count of posts within the specified verse range","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","example":5}}}}}},"400":{"description":"Invalid verse range - malformed keys or from > to"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/posts/by-verse/{verseKey}":{"get":{"operationId":"PostsController_getMyPostsByVerse","summary":"Get posts by verse","description":"Retrieve all posts written by the current user for a specific Quran verse. Returns posts referencing the exact verse key.","parameters":[{"name":"verseKey","required":true,"in":"path","description":"Verse key in format chapter:verse","schema":{"pattern":"VERSE_KEY_REGEX","example":"2:255","type":"string"}}],"responses":{"200":{"description":"User posts for the specified verse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedResponseDto"}}}},"400":{"description":"Invalid verse key format"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/tags":{"get":{"operationId":"TagsController_find","summary":"Search and retrieve tags","description":"Search for tags by query string. Returns paginated results matching the search term. Useful for tag autocomplete and discovery features.","parameters":[{"name":"query","required":false,"in":"query","description":"Search term","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"type":"number"}}],"responses":{"200":{"description":"Tags matching search query with pagination","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}}}}}},"tags":["Tags"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/comments":{"post":{"operationId":"CommentsController_create","summary":"Create a new comment","description":"Add a comment to a post or reply to an existing comment. Supports mentions and notifies the post author.","parameters":[],"requestBody":{"required":true,"description":"Comment with postId and optional parentId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentBody"}}}},"responses":{"201":{"description":"Comment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommentResponse"}}}},"400":{"description":"Invalid comment - empty body or invalid postId"},"401":{"description":"User not authenticated"},"404":{"description":"Post or parent comment not found"}},"tags":["Comments"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/comments/{id}/delete":{"get":{"operationId":"CommentsController_deleteComment","summary":"Delete a comment","description":"Soft-delete a comment. Only the author or admins can delete. Replies remain visible with placeholder.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric comment ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Comment deleted","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"boolean","example":true}}}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to delete this comment"},"404":{"description":"Comment not found"}},"tags":["Comments"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/comments/{id}/toggle-like":{"post":{"operationId":"CommentsController_toggleLike","summary":"Toggle like/unlike a comment","description":"Toggle like status. If liked, removes like. Notifies comment author on new likes.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric comment ID","schema":{"type":"number"}}],"responses":{"200":{"description":"Like toggled","content":{"application/json":{"schema":{"type":"object","properties":{"liked":{"type":"boolean","description":"true if liked, false if unliked"}}}}}},"401":{"description":"User not authenticated"},"404":{"description":"Comment not found"}},"tags":["Comments"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}},"/v1/comments/{id}/replies":{"get":{"operationId":"CommentsController_get","summary":"Get replies to a comment","description":"Retrieve paginated replies (nested comments) for a parent comment with author info.","parameters":[{"name":"id","required":true,"in":"path","description":"Parent comment ID","schema":{"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Number of results to return","schema":{"minimum":1,"maximum":20,"default":20,"type":"number"}},{"name":"page","required":false,"in":"query","description":"Page number","schema":{"minimum":1,"default":1,"type":"number"}}],"responses":{"200":{"description":"Comment replies with pagination","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CommentRepliesResponse"}}}},"404":{"description":"Parent comment not found"}},"tags":["Comments"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}]}}}} \ No newline at end of file +{ + "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 ## 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" + }, + "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": { + "Bookmark": { + "type": "object", + "properties": { + "id": { "type": "string", "example": "cmkthm7rb0005r4jq3r20ge06" }, + "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", "example": 5 }, + "group": { "type": "string" } + }, + "required": ["id", "createdAt", "type", "key"], + "additionalProperties": false + }, + "Collection": { + "type": "object", + "properties": { + "id": { "type": "string", "example": "cmkthm7sk0007r4jq6spyau75" }, + "updatedAt": { + "type": "string", + "format": "date-time", + "example": "2023-01-21T07:28:13.023Z" + }, + "name": { "type": "string", "example": "Woman in Quran" } + }, + "required": ["id", "updatedAt", "name"], + "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:10" }, + { "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 + }, + "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" + } + }, + "required": [ + "tafsirFontScale", + "quranTextFontScale", + "translationFontScale", + "wordByWordFontScale", + "reflectionFontScale", + "qnaFontScale", + "lessonFontScale" + ], + "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": "cmkthm84w000er4jq7r9u47p2" }, + "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" }, + "photoUrl": { + "type": "string", + "example": "https://photos.quran.com/img/muhajir.jpg" + } + }, + "additionalProperties": false + }, + "EditProfileDto": { + "type": "object", + "properties": { + "languageId": { "type": "number" }, + "reflectionLanguages": { + "type": "array", + "items": { "type": "string" } + }, + "ayahLanguages": { "type": "array", "items": { "type": "string" } }, + "customized": { "type": "boolean" } + } + }, + "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" + } + }, + "createdAt": { "type": "object", "example": "2000-01-21 00:00:00" }, + "joiningYear": { "type": "number", "example": 2025 }, + "isPasswordSet": { "type": "boolean", "example": true }, + "settings": { + "type": "object", + "properties": { + "ayahLanguages": { + "required": false, + "type": "array", + "items": { "type": "number" } + }, + "reflectionLanguages": { + "required": false, + "type": "array", + "items": { "type": "number" } + } + } + }, + "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 }, + "averageToxicity": { "type": "number", "default": 0 }, + "languageId": { "type": "number" }, + "banned": { "type": "boolean", "default": false }, + "memberType": { "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", "createdAt", "joiningYear", "settings", "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"] + }, + "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"] + }, + "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/UserSerializedDto" } + } + }, + "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" + } + } + }, + "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 } + }, + "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 }, + "name": { "type": "string" }, + "description": { "type": "string" }, + "organizationWebsite": { "type": "string" }, + "country": { "type": "string" }, + "url": { "type": "string" } + }, + "required": ["id"] + }, + "InviteUserDto": { + "type": "object", + "properties": { + "userIds": { "type": "array", "items": { "type": "string" } }, + "emails": { "type": "array", "items": { "type": "string" } } + }, + "required": ["userIds", "emails"] + }, + "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" } + }, + "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" } + }, + "required": ["name", "url"] + }, + "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"] + }, + "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" }, + "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"] + }, + "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": { + "post": { "$ref": "#/components/schemas/PostSerialized" }, + "success": { "type": "boolean" } + }, + "required": ["post", "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", "default": "" } + }, + "required": ["abuse", "comments"] + }, + "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": [ + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "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" + } + }, + "required": ["name"], + "additionalProperties": false + } + } + } + }, + "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 + } + } + }, + "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 + } + } + } + } + } + }, + "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": "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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/collections/{collectionId}/bookmarks": { + "post": { + "description": "Add a bookmark to an existing collection.", + "tags": ["Collections"], + "summary": "Add collection Bookmark", + "parameters": [ + { + "in": "path", + "name": "collectionId", + "schema": { + "type": "string", + "description": "The Id of the collection to be added.", + "example": "cmkthm7ui0008r4jq9bmzc243" + }, + "required": true, + "description": "The Id of the collection to be added." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "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 }, + "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", + "example": 4 + } + }, + "required": ["key", "verseNumber", "mushaf"], + "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" + }, + "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", + "example": 4 + } + }, + "required": ["key", "mushaf"], + "additionalProperties": false, + "title": "Surah, Juz, Or Page" + } + ] + } + } + } + }, + "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 + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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": "cmkthm7up0009r4jqfaqg4iha" + }, + "required": true, + "description": "The Id of the collection to be deleted." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "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 + } + } + }, + "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 + } + } + } + } + } + }, + "get": { + "description": "Get all resources that belong to an existing collection by collection id.", + "tags": ["Collections"], + "summary": "Get collection items by id", + "parameters": [ + { + "in": "path", + "name": "collectionId", + "schema": { + "type": "string", + "example": "cmkthm7vj000cr4jqdkfabg59" + } + }, + { + "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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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/Bookmark" } + } + }, + "additionalProperties": false + }, + "pagination": { + "type": "object", + "properties": { + "startCursor": { + "type": "string", + "example": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + }, + "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." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The new name of the collection to be updated." + } + }, + "required": ["name"], + "additionalProperties": 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": ["collection renamed"] } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + } + }, + "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 + } + } + } + } + } + } + }, + "/v1/collections/{collectionId}/bookmarks/{bookmarkId}": { + "delete": { + "description": "Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.", + "tags": ["Collections"], + "summary": "Delete collection bookmark by id", + "parameters": [ + { + "in": "path", + "name": "collectionId", + "schema": { + "type": "string", + "description": "The Id of the collection to be deleted.", + "example": "cmkthm7uu000ar4jqhzbcdlql" + }, + "required": true, + "description": "The Id of the collection to be deleted." + }, + { + "in": "path", + "name": "bookmarkId", + "schema": { + "type": "string", + "description": "The Id of the bookmark to be deleted.", + "example": "cmkthm7uu000br4jqc2ec5h49" + }, + "required": true, + "description": "The Id of the bookmark to be deleted." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "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 + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/bookmarks": { + "post": { + "description": "Add a bookmark by details.", + "tags": ["Bookmarks"], + "summary": "Add user bookmark", + "parameters": [ + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "anyOf": [ + { + "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 + }, + "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", + "example": 4 + } + }, + "required": ["key", "type", "verseNumber", "mushaf"], + "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" + }, + "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", + "example": 4 + } + }, + "required": ["key", "type", "mushaf"], + "additionalProperties": false, + "title": "Surah, Juz, Or page" + } + ] + } + } + } + }, + "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 + } + } + }, + "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 + } + } + } + } + } + }, + "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": "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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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/Bookmark" } + }, + "pagination": { + "type": "object", + "properties": { + "startCursor": { + "type": "string", + "example": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/bookmarks/{bookmarkId}": { + "delete": { + "description": "Delete a bookmark by id.", + "tags": ["Bookmarks"], + "summary": "Delete Bookmark", + "parameters": [ + { + "in": "path", + "name": "bookmarkId", + "schema": { + "type": "string", + "description": "The id of the bookmark to be deleted.", + "example": "cmkthm7rj0006r4jq3w04aolo" + }, + "required": true, + "description": "The id of the bookmark to be deleted." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "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 + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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/Bookmark" } + }, + "pagination": { + "type": "object", + "properties": { + "startCursor": { + "type": "string", + "example": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/bookmarks/bookmark": { + "get": { + "description": "Get a bookmark by details", + "tags": ["Bookmarks"], + "summary": "Get bookmark", + "parameters": [ + { + "in": "query", + "name": "key", + "schema": { + "type": "integer", + "description": "Surah, Juz or page number.", + "example": 2 + }, + "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": "verseNumber", + "schema": { + "type": "integer", + "description": "The Ayah number of the bookmark" + }, + "required": false, + "description": "The Ayah number of the bookmark" + }, + { + "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", + "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": { "$ref": "#/components/schemas/Bookmark" } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/bookmarks/collections": { + "get": { + "description": "Get all collections that a bookmark belongs to by bookmark details.", + "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": "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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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/Collection" } + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/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, + "anyOf": [ + { + "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", + "quranFont", + "mushafLines" + ] + } + }, + "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 + } + ] + } + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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" } + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/v1/reading-sessions": { + "post": { + "description": "Create or update an existing reading session. Reading session is used to keep track of recently read Ayahs. A 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.", + "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 to be added to reading session." + }, + "verseNumber": { + "type": "integer", + "minimum": 1, + "description": "The Ayah number to be added to reading session." + } + }, + "required": ["chapterNumber", "verseNumber"], + "additionalProperties": 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": ["reading session created"] } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + }, + "get": { + "description": "Get all existing reading sessions.", + "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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/goals/get-todays-plan": { + "get": { + "description": "Get today's goal plan.", + "tags": ["Goals"], + "summary": "Get today's goal plan", + "parameters": [ + { + "in": "query", + "name": "type", + "schema": { + "type": "string", + "enum": [ + "QURAN_TIME", + "QURAN_PAGES", + "QURAN_RANGE", + "COURSE", + "QURAN_READING_PROGRAM" + ], + "description": "The type of the goal.", + "example": "QURAN_TIME" + }, + "required": true, + "description": "The type 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": { + "hasGoal": { + "type": "boolean", + "description": "User has a goal.", + "example": false + } + }, + "required": ["hasGoal"], + "additionalProperties": false, + "oneOf": [ + { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The id of the activity day.", + "example": "cmkthm7ms0004r4jq82u23hpc" + }, + "date": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "The date of the activity day.", + "example": "2023-09-31" + }, + "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 type of the activity day", + "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", + "title": "When user has a goal" + } + ] + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/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": "cmkthm7wi000dr4jq0w3geidl" + }, + "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" + ], + "description": "The type of the goal.", + "example": "QURAN_TIME" + }, + "amount": { + "oneOf": [ + { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$", + "example": "1:5-1:10", + "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"], + "description": "The category of the goal" + } + }, + "additionalProperties": 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": {}, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + }, + "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": "cmkthm7wi000dr4jq0w3geidl" + }, + "required": true, + "description": "The id of the goal." + }, + { + "in": "query", + "name": "category", + "schema": { + "type": "string", + "enum": ["QURAN", "COURSE", "QURAN_READING_PROGRAM"], + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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" + ], + "description": "The type of the goal.", + "example": "QURAN_TIME" + }, + "amount": { + "oneOf": [ + { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$", + "example": "1:5-1:10", + "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"], + "description": "The category of the goal" + } + }, + "required": ["type", "amount", "category"], + "additionalProperties": 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": { + "id": { + "type": "string", + "description": "The id of the goal.", + "example": "cmkthm7wi000dr4jq0w3geidl" + } + }, + "required": ["id"], + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/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" + ], + "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:10", + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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-31" + }, + "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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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 streak.", + "example": "cmkthm85f000fr4jq7l9khj0j" + }, + "startDate": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "The date of the streak.", + "example": "2023-09-01" + }, + "endDate": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "The date of the streak.", + "example": "2023-09-31" + }, + "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", + "status", + "days" + ], + "additionalProperties": false + } + }, + "pagination": { + "type": "object", + "properties": { + "startCursor": { + "type": "string", + "example": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/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": "array", + "items": { + "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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/v1/activity-days": { + "post": { + "description": "Add or update an activity day.", + "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": "The date of the activity day, can be today or a past date. If not passed, default to today", + "example": "2023-09-01" + }, + "type": { + "type": "string", + "enum": ["QURAN", "LESSON", "QURAN_READING_PROGRAM"], + "description": "The type of the activity day", + "example": "QURAN" + } + }, + "required": ["type"], + "additionalProperties": false, + "oneOf": [ + { + "type": "object", + "properties": { + "seconds": { + "type": "integer", + "minimum": 1, + "description": "Seconds spent reading the current request's 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": "Current request's read range of Ayahs", + "example": ["1:5-1:10"] + }, + "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" + } + ] + } + } + } + }, + "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 + } + } + } + }, + "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 + } + } + } + } + } + }, + "get": { + "description": "Get user activity days.", + "tags": ["Activity Days"], + "summary": "Get activity days", + "parameters": [ + { + "in": "query", + "name": "from", + "schema": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "The start date of the activity days", + "example": "2023-09-01" + }, + "description": "The start date of the activity days" + }, + { + "in": "query", + "name": "to", + "schema": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "The last date of the activity days", + "example": "2023-09-31" + }, + "description": "The last date of the activity days" + }, + { + "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 type of the activity day", + "example": "QURAN" + }, + "description": "The type of the activity day" + }, + { + "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": "cmkthm7m70000r4jq8fv86xcq" + }, + "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": "cmkthm7m70001r4jqfl9j81bv" + }, + "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": "cmkthm7ms0004r4jq82u23hpc" + }, + "date": { + "type": "string", + "pattern": "^\\d{4}-\\d{2}-\\d{2}$", + "description": "The date of the activity day.", + "example": "2023-09-31" + }, + "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 type of the activity day", + "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": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/activity-days/estimate-reading-time": { + "get": { + "description": "Estimate the number of seconds it would take to read a range. We estimate it based on the average reading speed we have collected 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 + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/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": { + "required": true, + "description": "Settings fields to update - only include fields you want to change", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/EditProfileDto" } + } + } + }, + "responses": { + "200": { + "description": "Settings updated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": true } + } + } + } + } + }, + "400": { "description": "Invalid settings data" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + }, + "get": { + "operationId": "UsersController_profile", + "summary": "Get user profile", + "description": "Retrieve the complete profile of the authenticated user including personal info, settings, statistics, and connected accounts.", + "parameters": [ + { + "name": "qdc", + "required": false, + "in": "query", + "description": "Include Quran.com (QDC) connected account data", + "schema": { "type": "boolean" } + } + ], + "responses": { + "200": { + "description": "Full user profile with all data", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UserSerializedDto" } + } + } + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + }, + "put": { + "operationId": "UsersController_updateProfile", + "summary": "Update user profile", + "description": "Update user profile information including name, bio, username, avatar, and social links. Validates username uniqueness.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Profile fields to update wrapped in a user object", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UpdateProfileBodyDto" } + } + } + }, + "responses": { + "200": { + "description": "Profile updated and returned with new values", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UserSerializedDto" } + } + } + }, + "400": { "description": "Invalid profile data or username taken" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/notes": { + "get": { + "tags": ["Notes"], + "description": "List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)", + "summary": "Get all notes", + "parameters": [ + { + "in": "query", + "name": "cursor", + "schema": { + "type": "string", + "description": "A cursor for pagination, used to fetch the next set of results.", + "example": "cursor123" + }, + "description": "A cursor for pagination, used to fetch the next set of results." + }, + { + "in": "query", + "name": "limit", + "schema": { + "type": "number", + "format": "float", + "minimum": 1, + "maximum": 50, + "description": "The maximum number of notes to return, defaults to 20.", + "example": 20, + "default": 20 + }, + "description": "The maximum number of notes to return, defaults to 20." + }, + { + "in": "query", + "name": "sortBy", + "schema": { + "type": "string", + "enum": ["newest", "oldest"], + "description": "The sorting order of the notes, defaults to newest first.", + "example": "newest", + "default": "newest" + }, + "description": "The sorting order of the notes, defaults to newest first." + } + ], + "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 unique identifier of the note.", + "example": "asdasdqwe1231" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "The creation date of the note.", + "example": "2023-01-21T07:28:13.023Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "The last update date of the note.", + "example": "2023-01-22T07:28:13.023Z" + }, + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "source": { + "type": "string", + "description": "The source of the note.", + "example": "we23412312weq" + }, + "attachedEntities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "description": "An array of attached entities associated with the note." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["id", "createdAt", "updatedAt", "body"], + "additionalProperties": false + } + }, + "pagination": { + "type": "object", + "properties": { + "startCursor": { + "type": "string", + "example": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + }, + "post": { + "tags": ["Notes"], + "description": "Add a new note.", + "summary": "Add note", + "parameters": [ + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "saveToQR": { + "type": "boolean", + "description": "Indicates whether the note should be saved to the QuranReflect.", + "example": true + }, + "attachedEntity": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["body", "saveToQR"], + "additionalProperties": 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": { + "id": { + "type": "string", + "description": "The unique identifier of the note.", + "example": "asdasdqwe1231" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "The creation date of the note.", + "example": "2023-01-21T07:28:13.023Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "The last update date of the note.", + "example": "2023-01-22T07:28:13.023Z" + }, + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "source": { + "type": "string", + "description": "The source of the note.", + "example": "we23412312weq" + }, + "attachedEntities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "description": "An array of attached entities associated with the note." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["id", "createdAt", "updatedAt", "body"], + "additionalProperties": false + } + }, + "additionalProperties": false + } + } + }, + "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 + } + } + } + } + } + } + }, + "/v1/notes/by-verse/:verseKey": { + "get": { + "tags": ["Notes"], + "description": "Retrieve notes by a specific verse.", + "summary": "Get notes by verse", + "parameters": [ + { + "in": "query", + "name": "verseKey", + "schema": { + "type": "string", + "pattern": "^(\\d+):(\\d+)$", + "description": "The verse key for which notes are being requested.", + "example": "2:255" + }, + "required": true, + "description": "The verse key for which notes are being requested." + } + ], + "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 unique identifier of the note.", + "example": "asdasdqwe1231" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "The creation date of the note.", + "example": "2023-01-21T07:28:13.023Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "The last update date of the note.", + "example": "2023-01-22T07:28:13.023Z" + }, + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "source": { + "type": "string", + "description": "The source of the note.", + "example": "we23412312weq" + }, + "attachedEntities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "description": "An array of attached entities associated with the note." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["id", "createdAt", "updatedAt", "body"], + "additionalProperties": false + } + }, + "pagination": { + "type": "object", + "properties": { + "startCursor": { + "type": "string", + "example": "cmkthm7m70002r4jqbbxjavgq" + }, + "endCursor": { + "type": "string", + "example": "cmkthm7m70003r4jqatt3c580" + }, + "hasNextPage": { "type": "boolean", "example": true }, + "hasPreviousPage": { + "type": "boolean", + "example": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/notes/by-attached-entity": { + "get": { + "tags": ["Notes"], + "description": "Retrieve notes by attached entity.", + "summary": "Get notes by attached entity", + "parameters": [ + { + "in": "query", + "name": "entityId", + "schema": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "required": true, + "description": "The unique identifier for the attached entity." + }, + { + "in": "query", + "name": "entityType", + "schema": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "required": true, + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values." + } + ], + "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 unique identifier of the note.", + "example": "asdasdqwe1231" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "The creation date of the note.", + "example": "2023-01-21T07:28:13.023Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "The last update date of the note.", + "example": "2023-01-22T07:28:13.023Z" + }, + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "source": { + "type": "string", + "description": "The source of the note.", + "example": "we23412312weq" + }, + "attachedEntities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "description": "An array of attached entities associated with the note." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["id", "createdAt", "updatedAt", "body"], + "additionalProperties": false + } + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/notes/count-within-range": { + "get": { + "tags": ["Notes"], + "description": "Get the count of notes within a range of verses.", + "summary": "Get notes count within verse range", + "parameters": [ + { + "in": "query", + "name": "from", + "schema": { + "type": "string", + "pattern": "^(\\d+):(\\d+)$", + "description": "The starting verse key of the range.", + "example": "2:12" + }, + "required": true, + "description": "The starting verse key of the range." + }, + { + "in": "query", + "name": "to", + "schema": { + "type": "string", + "pattern": "^(\\d+):(\\d+)$", + "description": "The ending verse key of the range.", + "example": "2:18" + }, + "required": true, + "description": "The ending verse key of the range." + } + ], + "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": { + "type": "integer", + "minimum": 1 + }, + "description": "A map of verse keys to note counts, where each key is a verse key and each value is an integer count of notes.", + "example": { "1:2": 5, "1:3": 1, "1:4": 1 } + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/notes/by-range": { + "get": { + "tags": ["Notes"], + "description": "Retrieve notes by a range of verses.", + "summary": "Get notes by verse range", + "parameters": [ + { + "in": "query", + "name": "from", + "schema": { + "type": "string", + "pattern": "^(\\d+):(\\d+)$", + "description": "The starting verse key of the range.", + "example": "2:12" + }, + "required": true, + "description": "The starting verse key of the range." + }, + { + "in": "query", + "name": "to", + "schema": { + "type": "string", + "pattern": "^(\\d+):(\\d+)$", + "description": "The ending verse key of the range.", + "example": "2:18" + }, + "required": true, + "description": "The ending verse key of the range." + } + ], + "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 unique identifier of the note.", + "example": "asdasdqwe1231" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "The creation date of the note.", + "example": "2023-01-21T07:28:13.023Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "The last update date of the note.", + "example": "2023-01-22T07:28:13.023Z" + }, + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "source": { + "type": "string", + "description": "The source of the note.", + "example": "we23412312weq" + }, + "attachedEntities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "description": "An array of attached entities associated with the note." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["id", "createdAt", "updatedAt", "body"], + "additionalProperties": false + } + } + }, + "additionalProperties": 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 + } + } + } + } + } + } + }, + "/v1/notes/:noteId": { + "get": { + "tags": ["Notes"], + "description": "Retrieve a note by its ID.", + "summary": "Get note by ID", + "parameters": [ + { + "in": "query", + "name": "withAttachedEntities", + "schema": { + "type": "boolean", + "description": "Specifies whether to include attached entities in the response, defaults to true.", + "example": true, + "default": true + }, + "description": "Specifies whether to include attached entities in the response, defaults to true." + } + ], + "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 unique identifier of the note.", + "example": "asdasdqwe1231" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "The creation date of the note.", + "example": "2023-01-21T07:28:13.023Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "The last update date of the note.", + "example": "2023-01-22T07:28:13.023Z" + }, + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "source": { + "type": "string", + "description": "The source of the note.", + "example": "we23412312weq" + }, + "attachedEntities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "description": "An array of attached entities associated with the note." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["id", "createdAt", "updatedAt", "body"], + "additionalProperties": false + } + }, + "additionalProperties": 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 + } + } + } + } + } + }, + "patch": { + "tags": ["Notes"], + "description": "Update a note by its ID.", + "summary": "Update note by ID", + "parameters": [ + { + "in": "path", + "name": "noteId", + "schema": { + "type": "string", + "description": "The unique identifier of the note to be retrieved or manipulated.", + "example": "asda12312312" + }, + "required": true, + "description": "The unique identifier of the note to be retrieved or manipulated." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "saveToQR": { + "type": "boolean", + "description": "Indicates whether the updated note should be saved to the QuranReflect, defaults to false.", + "example": false, + "default": false + } + }, + "required": ["body"], + "additionalProperties": 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": { + "id": { + "type": "string", + "description": "The unique identifier of the note.", + "example": "asdasdqwe1231" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "description": "The creation date of the note.", + "example": "2023-01-21T07:28:13.023Z" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "description": "The last update date of the note.", + "example": "2023-01-22T07:28:13.023Z" + }, + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "source": { + "type": "string", + "description": "The source of the note.", + "example": "we23412312weq" + }, + "attachedEntities": { + "type": "array", + "items": { + "type": "object", + "properties": { + "entityId": { + "type": "string", + "description": "The unique identifier for the attached entity.", + "example": "entity123" + }, + "entityType": { + "type": "string", + "enum": ["reflection"], + "description": "The type of the attached entity, must be one of the predefined NoteEntityType values.", + "example": "reflection" + }, + "entityMetadata": { + "type": "object", + "properties": {}, + "description": "Additional metadata for the attached entity.", + "example": { "key": "value" } + } + }, + "required": ["entityId", "entityType"], + "additionalProperties": false + }, + "description": "An array of attached entities associated with the note." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:255-2:257"] + } + }, + "required": ["id", "createdAt", "updatedAt", "body"], + "additionalProperties": false + } + }, + "additionalProperties": false + } + } + }, + "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 + } + } + } + } + } + }, + "delete": { + "tags": ["Notes"], + "description": "Delete a note by its ID.", + "summary": "Delete note by ID", + "parameters": [ + { + "in": "path", + "name": "noteId", + "schema": { + "type": "string", + "description": "The ID of the note to delete." + }, + "required": true, + "description": "The ID of the note to delete." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "responses": { + "200": { + "description": "Request has been handled successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": true }, + "data": { + "type": "object", + "properties": { "success": { "type": "boolean" } }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + } + }, + "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 + } + } + } + } + } + } + }, + "/v1/notes/:noteId/publish": { + "post": { + "tags": ["Notes"], + "description": "Publish a note to QR.", + "summary": "Publish note", + "parameters": [ + { + "in": "path", + "name": "noteId", + "schema": { + "type": "string", + "description": "The unique identifier of the note to be retrieved or manipulated.", + "example": "asda12312312" + }, + "required": true, + "description": "The unique identifier of the note to be retrieved or manipulated." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "body": { + "type": "string", + "minLength": 6, + "maxLength": 10000, + "description": "The main content of the note, must be between the specified minimum and maximum length.", + "example": "This is a sample note body." + }, + "ranges": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(\\d+):(\\d+)-(\\d+):(\\d+)$" + }, + "description": "An array of verse ranges associated with the note.", + "example": ["2:112-2:115"] + } + }, + "required": ["body"], + "additionalProperties": 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": { + "success": { "type": "boolean" }, + "postId": { "type": "number", "format": "float" } + }, + "required": ["success"], + "additionalProperties": false, + "description": "Response object indicating the success of the note publishing operation and the optional post ID if successful.", + "example": { "success": true, "postId": 123 } + } + }, + "additionalProperties": false + } + } + }, + "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 + } + } + } + } + } + } + }, + "/v1/sync/": { + "get": { + "description": "Get list of mutations that were applied to resources after a certain point in time.", + "tags": ["Sync"], + "summary": "Get mutations", + "parameters": [ + { + "in": "query", + "name": "mutationsSince", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp to get mutations since.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp to get mutations since." + }, + { + "in": "query", + "name": "resources", + "schema": { + "type": "string", + "description": "Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.", + "example": "BOOKMARK,COLLECTION" + }, + "required": false, + "description": "Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned." + }, + { + "in": "query", + "name": "metadataOnly", + "schema": { + "type": "boolean", + "description": "When true, only returns lastMutationAt without mutations.", + "example": true, + "default": false + }, + "required": false, + "description": "When true, only returns lastMutationAt without mutations." + }, + { + "in": "query", + "name": "limit", + "schema": { + "type": "number", + "format": "float", + "minimum": 1, + "maximum": 1000, + "description": "Maximum number of mutations to return per page (1-1000).", + "example": 100, + "default": 100 + }, + "required": false, + "description": "Maximum number of mutations to return per page (1-1000)." + }, + { + "in": "query", + "name": "page", + "schema": { + "type": "number", + "format": "float", + "minimum": 1, + "description": "Page number (1-based).", + "example": 1, + "default": 1 + }, + "required": false, + "description": "Page number (1-based)." + } + ], + "responses": { + "200": { + "description": "Request has been handled successfully.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": true }, + "data": { + "type": "object", + "properties": { + "mutations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["CREATE", "UPDATE", "DELETE"], + "description": "The type of the mutation", + "example": "CREATE" + }, + "resource": { + "type": "string", + "enum": [ + "BOOKMARK", + "COLLECTION", + "COLLECTION_BOOKMARK", + "NOTE" + ], + "description": "The resource the mutation was applied to.", + "example": "BOOKMARK" + }, + "resourceId": { + "type": "string", + "description": "The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.", + "example": "lqc794i0qnxq4pdlfanfbd2r" + }, + "data": { + "type": "object", + "properties": {}, + "description": "The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.", + "example": { + "bookmarkType": "ayah", + "bookmarkGroup": "verses_6236", + "key": 6, + "verseNumber": 3 + } + }, + "timestamp": { + "type": "number", + "format": "float", + "description": "Unix timestamp when the latest mutation of the resource occurred", + "example": 1731636500303 + } + }, + "required": ["type", "resource", "timestamp"], + "additionalProperties": false, + "description": "Represents a single mutation/change to a resource" + }, + "description": "Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.", + "example": [ + { + "type": "CREATE", + "resource": "BOOKMARK", + "resourceId": "lqc794i0qnxq4pdlfanfbd2r", + "data": { + "bookmarkType": "ayah", + "bookmarkGroup": "verses_6236", + "key": 6, + "verseNumber": 3 + }, + "timestamp": 1731636500303 + } + ] + }, + "page": { + "type": "number", + "format": "float", + "description": "Current page number", + "example": 1 + }, + "limit": { + "type": "number", + "format": "float", + "description": "Items per page", + "example": 100 + }, + "total": { + "type": "number", + "format": "float", + "description": "Total number of mutations", + "example": 150 + }, + "hasMore": { + "type": "boolean", + "description": "Whether more pages exist", + "example": true + }, + "lastMutationAt": { + "type": "number", + "format": "float", + "description": "Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.", + "example": 1731636500303 + } + }, + "required": ["lastMutationAt"], + "additionalProperties": false, + "description": "Response schema for get mutations endpoint" + } + }, + "additionalProperties": 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 + } + } + } + } + } + }, + "post": { + "description": "An endpoint to sync local mutations to the server.", + "tags": ["Sync"], + "summary": "Sync local mutations", + "parameters": [ + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected." + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "mutations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["CREATE", "UPDATE", "DELETE"], + "description": "The type of the mutation", + "example": "CREATE" + }, + "resource": { + "type": "string", + "enum": [ + "BOOKMARK", + "COLLECTION", + "COLLECTION_BOOKMARK", + "NOTE" + ], + "description": "Resource the mutation applies to.", + "example": "BOOKMARK" + }, + "resourceId": { + "type": "string", + "description": "Server's ID for finding the resource during update/delete operations.", + "example": "lqc794i0qnxq4pdlfanfbd2r" + }, + "data": { + "type": "object", + "properties": {}, + "description": "Resource data. Format depends on resource type.", + "example": { + "bookmarkType": "ayah", + "bookmarkGroup": "verses_6236", + "key": 6, + "verseNumber": 3 + } + } + }, + "required": ["type", "resource"], + "additionalProperties": false, + "description": "Represents a single mutation/change to a resource" + } + } + }, + "required": ["mutations"], + "additionalProperties": 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": { + "mutations": { + "type": "array", + "items": { + "type": "object", + "properties": { + "type": { + "type": "string", + "enum": ["CREATE", "UPDATE", "DELETE"], + "description": "The type of the mutation", + "example": "CREATE" + }, + "resource": { + "type": "string", + "enum": [ + "BOOKMARK", + "COLLECTION", + "COLLECTION_BOOKMARK", + "NOTE" + ], + "description": "The resource the mutation was applied to.", + "example": "BOOKMARK" + }, + "resourceId": { + "type": "string", + "description": "The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.", + "example": "lqc794i0qnxq4pdlfanfbd2r" + }, + "data": { + "type": "object", + "properties": {}, + "description": "The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.", + "example": { + "bookmarkType": "ayah", + "bookmarkGroup": "verses_6236", + "key": 6, + "verseNumber": 3 + } + }, + "timestamp": { + "type": "number", + "format": "float", + "description": "Unix timestamp when the latest mutation of the resource occurred", + "example": 1731636500303 + } + }, + "required": ["type", "resource", "timestamp"], + "additionalProperties": false, + "description": "Represents a single mutation/change to a resource" + }, + "description": "Array of mutations that were successfully applied on the server.", + "example": [ + { + "type": "CREATE", + "resource": "BOOKMARK", + "resourceId": "lqc794i0qnxq4pdlfanfbd2r", + "data": { + "bookmarkType": "ayah", + "bookmarkGroup": "verses_6236", + "key": 6, + "verseNumber": 3 + }, + "timestamp": 1731636500303 + } + ] + }, + "page": { + "type": "number", + "format": "float", + "description": "Current page number", + "example": 1 + }, + "limit": { + "type": "number", + "format": "float", + "description": "Items per page", + "example": 100 + }, + "total": { + "type": "number", + "format": "float", + "description": "Total number of mutations", + "example": 150 + }, + "hasMore": { + "type": "boolean", + "description": "Whether more pages exist", + "example": true + }, + "lastMutationAt": { + "type": "number", + "format": "float", + "description": "Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.", + "example": 1731636500303 + } + }, + "required": ["lastMutationAt"], + "additionalProperties": false, + "description": "Response schema for post mutations endpoint" + } + }, + "additionalProperties": 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 + } + } + } + }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + } + } + }, + "422": { + "description": "Validation Error. The request includes one or more invalid params.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "ValidationError" + }, + "message": { + "type": "string", + "example": "Invalid mutations" + } + } + } + } + }, + "examples": { + "Invalid mutations format": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Invalid mutations" + } + } + }, + "Too many mutations": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Mutations must not exceed 100" + } + } + }, + "Missing resource": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Missing resource at mutation[0]" + } + } + }, + "Invalid resource": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Invalid resource: \"invalidResource\" at mutation[0]" + } + } + }, + "Missing mutation type": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Missing mutation type at mutation[0]" + } + } + }, + "Invalid mutation type": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Invalid mutation type: \"invalidType\" at mutation[0]" + } + } + }, + "Missing resourceId": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Missing resourceId at mutation[0]" + } + } + }, + "Invalid resourceId type": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Invalid resourceId at mutation[0]" + } + } + }, + "Missing data": { + "value": { + "success": false, + "error": { + "code": "ValidationError", + "message": "Missing data at mutation[0]" + } + } + } + } + } + } + }, + "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 + } + } + } + } + } + } + }, + "/v1/users/my-rooms": { + "get": { + "operationId": "UsersController_rooms", + "summary": "Get logged-in user rooms", + "description": "Retrieve all rooms (groups and pages) the authenticated user is a member of. Supports filtering by name and pagination.", + "parameters": [ + { + "name": "name", + "required": false, + "in": "query", + "description": "Filter rooms by name", + "schema": { "type": "string" } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "type": "number" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Rooms per page (default: 10)", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "User rooms with pagination metadata", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UserRoomsResponse" } + } + } + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users/search": { + "get": { + "operationId": "UsersController_search", + "summary": "Search for users", + "description": "Search users by name or username. Supports mentioning in posts, finding users for room invites, and general discovery. Results can be scoped to specific contexts.", + "parameters": [ + { + "name": "query", + "required": false, + "in": "query", + "description": "Search term for name/username", + "schema": { "type": "string" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Results per page (default: 10)", + "schema": { "type": "number" } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "type": "number" } + }, + { + "name": "all", + "required": false, + "in": "query", + "description": "Search all users (not just followed)", + "schema": { "type": "boolean" } + }, + { + "name": "postingAs", + "required": false, + "in": "query", + "description": "Filter for posting-as feature", + "schema": { "type": "boolean" } + }, + { + "name": "postingAsUserId", + "required": false, + "in": "query", + "description": "User ID for posting-as context", + "schema": { "type": "string" } + }, + { + "name": "roomId", + "required": false, + "in": "query", + "description": "Room ID for scoped search", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Matching users with pagination", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UsersSearchResponse" } + } + } + } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users/{followeeId}/toggle-follow": { + "post": { + "operationId": "UsersController_toggleFollow", + "summary": "Toggle follow/unfollow a user", + "description": "Follow or unfollow another user. When following, their posts will appear in your FOLLOWING feed. Can optionally specify action to force follow/unfollow.", + "parameters": [ + { + "name": "followeeId", + "required": true, + "in": "path", + "description": "UUID of the user to follow/unfollow", + "schema": { "type": "string" } + } + ], + "requestBody": { + "required": false, + "description": "Optional: specify \"follow\" or \"unfollow\" action explicitly", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/ToggleFollowDto" } + } + } + }, + "responses": { + "200": { + "description": "Follow status changed - returns new state", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "followed": { + "type": "boolean", + "description": "true if now following" + } + } + } + } + } + }, + "400": { + "description": "Cannot follow yourself or action already in desired state" + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users/{followerId}/remove-follower": { + "post": { + "operationId": "UsersController_removeFollower", + "summary": "Remove a follower", + "description": "Remove a user from your followers list. They will no longer see you as followed and won't receive notifications about your activity.", + "parameters": [ + { + "name": "followerId", + "required": true, + "in": "path", + "description": "UUID of the follower to remove", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Follower removed successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "removed": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "404": { "description": "Follower relationship not found" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users/{id}": { + "get": { + "operationId": "UsersController_getUserProfile", + "summary": "Get user profile by id or username", + "description": "Retrieve a user profile by either UUID or username. If viewing your own profile, returns full data; otherwise returns public profile with follow relationship status.", + "parameters": [ + { + "name": "id", + "required": false, + "in": "path", + "description": "UUID of the user", + "schema": { "type": "string" } + }, + { + "name": "username", + "required": false, + "in": "path", + "description": "Username of the user (case-insensitive)", + "schema": { "type": "string" } + }, + { + "name": "qdc", + "required": false, + "in": "query", + "description": "Include Quran.com connected account data", + "schema": { "type": "boolean" } + } + ], + "responses": { + "200": { + "description": "Own profile with full data including settings", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UserSerializedDto" } + } + } + }, + "404": { "description": "User not found" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users/{username}/profile": { + "get": { + "operationId": "UsersController_getUserProfile", + "summary": "Get user profile by id or username", + "description": "Retrieve a user profile by either UUID or username. If viewing your own profile, returns full data; otherwise returns public profile with follow relationship status.", + "parameters": [ + { + "name": "id", + "required": false, + "in": "path", + "description": "UUID of the user", + "schema": { "type": "string" } + }, + { + "name": "username", + "required": false, + "in": "path", + "description": "Username of the user (case-insensitive)", + "schema": { "type": "string" } + }, + { + "name": "qdc", + "required": false, + "in": "query", + "description": "Include Quran.com connected account data", + "schema": { "type": "boolean" } + } + ], + "responses": { + "200": { + "description": "Own profile with full data including settings", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UserSerializedDto" } + } + } + }, + "404": { "description": "User not found" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users/{id}/followers": { + "get": { + "operationId": "UsersController_getUserFollowers", + "summary": "Get user followers", + "description": "Retrieve a paginated list of users who follow the specified user. Includes follow relationship to the viewer if authenticated.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "UUID of the user", + "schema": { "type": "string" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Results per page (default: 10)", + "schema": { + "minimum": 1, + "maximum": 20, + "default": 20, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + } + ], + "responses": { + "200": { "description": "List of followers with pagination" }, + "404": { "description": "User not found" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users/{id}/following": { + "get": { + "operationId": "UsersController_getUserFollowing", + "summary": "Get users followed by user", + "description": "Retrieve a paginated list of users that the specified user follows. Includes follow relationship to the viewer if authenticated.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "UUID of the user", + "schema": { "type": "string" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Results per page (default: 10)", + "schema": { + "minimum": 1, + "maximum": 20, + "default": 20, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + } + ], + "responses": { + "200": { "description": "List of followed users with pagination" }, + "404": { "description": "User not found" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/users": { + "delete": { + "operationId": "UsersController_deleteAccount", + "summary": "Delete user account permanently", + "description": "Permanently delete the authenticated user account and all associated data from QuranReflect and Quran.com. This action is irreversible. The user is immediately banned to prevent further actions, then all data is deleted in the background. All posts, comments, likes, preferences, and memberships will be removed. If the user owns rooms, posts by other members will be converted to global posts.", + "parameters": [], + "responses": { + "200": { + "description": "Account deletion initiated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": true }, + "message": { + "type": "string", + "example": "Account deletion initiated successfully" + } + } + } + } + } + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Users"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/admins-access": { + "post": { + "operationId": "RoomsController_adminsAccess", + "summary": "Update room admin access", + "description": "Grant or revoke admin privileges for a user in a room. Only room owners or existing admins can modify admin access.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Contains roomId, userId, and admin boolean to grant/revoke access", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/RoomAdminUpdateDto" } + } + } + }, + "responses": { + "200": { + "description": "Admin access updated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { "description": "User not authorized to modify admin access" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/groups": { + "patch": { + "operationId": "RoomsController_updateGroup", + "summary": "Update a group", + "description": "Update group properties like name, description, URL, avatar, country, or public visibility. Only group admins/owners can update.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Group fields to update - all fields optional except id", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UpdateGroupDto" } + } + } + }, + "responses": { + "200": { + "description": "Group updated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean" }, + "room": { "type": "object" } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { "description": "User not authorized to update this group" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + }, + "post": { + "operationId": "RoomsController_createNewGroup", + "summary": "Create a new group", + "description": "Create a new community group for sharing reflections. Groups can be public or private, and the creator becomes the owner.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Group creation details including name, description, URL, and visibility", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/CreateGroupDto" } + } + } + }, + "responses": { + "201": { "description": "Group created successfully" }, + "400": { "description": "Invalid group data or URL already taken" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/pages": { + "patch": { + "operationId": "RoomsController_updatePage", + "summary": "Update a page", + "description": "Update page properties like name, description, contact info, organization details, or visibility. Only page admins/owners can update.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Page fields to update - all fields optional except id", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UpdatePageDto" } + } + } + }, + "responses": { + "200": { + "description": "Page updated successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean" }, + "room": { "type": "object" } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { "description": "User not authorized to update this page" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + }, + "post": { + "operationId": "RoomsController_createNewPage", + "summary": "Create a new page", + "description": "Submit a request to create a new organizational page. Pages require admin approval and include organization details, contact info, and purpose statement.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Page creation details including name, description, URL, organization info, and purpose", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/CreatePageDto" } + } + } + }, + "responses": { + "201": { + "description": "Page request submitted for admin review", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean" }, + "data": { "type": "object" }, + "message": { "type": "string" } + } + } + } + } + }, + "400": { "description": "Invalid page data or URL already taken" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{id}/members": { + "get": { + "operationId": "RoomsController_getRoomMembers", + "summary": "Get room members", + "description": "Retrieve paginated list of members in a room (group or page). Returns user profiles with their roles.", + "parameters": [ + { + "name": "limit", + "required": false, + "in": "query", + "description": "Members per page (default: 10)", + "schema": { "type": "number" } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "type": "number" } + }, + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { "description": "Room members retrieved with pagination" }, + "404": { "description": "Room not found" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{id}/invite": { + "post": { + "operationId": "RoomsController_inviteUserToRoom", + "summary": "Invite user to room", + "description": "Send an invitation to a user to join the room. User will receive a notification/email with an invite link. Only admins can invite.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + } + ], + "requestBody": { + "required": true, + "description": "User identification for invitation (email or userId)", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/InviteUserDto" } + } + } + }, + "responses": { + "200": { "description": "Invitation sent successfully" }, + "401": { "description": "User not authenticated" }, + "403": { "description": "User not authorized to invite members" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{id}/accept-invite": { + "get": { + "operationId": "RoomsController_acceptInvite", + "summary": "Accept room invite", + "description": "Accept an invitation to join a room using the token from the invite link. Adds user as member.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + }, + { + "name": "token", + "required": true, + "in": "query", + "description": "Invitation token from invite link", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Invitation accepted - user is now a member" + }, + "400": { "description": "Invalid or expired token" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{id}/reject-invite": { + "get": { + "operationId": "RoomsController_rejectInvite", + "summary": "Reject room invite", + "description": "Decline an invitation to join a room. Invalidates the invite token.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + }, + { + "name": "token", + "required": true, + "in": "query", + "description": "Invitation token from invite link", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { "description": "Invitation rejected" }, + "400": { "description": "Invalid or expired token" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{id}/members/{userId}": { + "delete": { + "operationId": "RoomsController_removeMember", + "summary": "Remove member from room", + "description": "Remove a user from a room (group or page). Only admins can remove other members. Users can remove themselves.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + }, + { + "name": "userId", + "required": true, + "in": "path", + "description": "UUID of the user to remove", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Member removed successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { "success": { "type": "boolean" } } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { "description": "User not authorized to remove this member" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/joined-rooms": { + "get": { + "operationId": "RoomsController_getRooms", + "summary": "Get joined or managed rooms", + "description": "Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.", + "parameters": [ + { + "name": "query", + "required": false, + "in": "query", + "description": "Search query for room names", + "schema": { "type": "string" } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Rooms per page (default: 5)", + "schema": { + "minimum": 1, + "maximum": 5, + "default": 5, + "type": "number" + } + } + ], + "responses": { + "200": { "description": "Rooms retrieved with pagination" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/managed-rooms": { + "get": { + "operationId": "RoomsController_getRooms", + "summary": "Get joined or managed rooms", + "description": "Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.", + "parameters": [ + { + "name": "query", + "required": false, + "in": "query", + "description": "Search query for room names", + "schema": { "type": "string" } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Rooms per page (default: 5)", + "schema": { + "minimum": 1, + "maximum": 5, + "default": 5, + "type": "number" + } + } + ], + "responses": { + "200": { "description": "Rooms retrieved with pagination" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/search": { + "get": { + "operationId": "RoomsController_searchRooms", + "summary": "Search rooms", + "description": "Search for public groups and pages by name or description. Results can be filtered by room type.", + "parameters": [ + { + "name": "query", + "required": false, + "in": "query", + "description": "Search term for room name/description", + "schema": { "type": "string" } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "type": "number" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Results per page (default: 10)", + "schema": { "type": "number" } + }, + { + "name": "roomType", + "required": false, + "in": "query", + "description": "Filter by room type: GROUP or PAGE", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { "description": "Matching rooms with pagination" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/group/{url}": { + "get": { + "operationId": "RoomsController_getRoomProfile", + "summary": "Get room profile by URL or subdomain", + "description": "Retrieve a room profile by its unique URL (for groups) or subdomain (for pages). Returns room details, member counts, and relationship status.", + "parameters": [ + { + "name": "url", + "required": false, + "in": "path", + "description": "Group URL identifier (lowercase)", + "schema": { "type": "string" } + }, + { + "name": "subdomain", + "required": false, + "in": "path", + "description": "Page subdomain identifier (lowercase)", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Room profile with details and membership info" + }, + "404": { "description": "Room not found" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/page/{subdomain}": { + "get": { + "operationId": "RoomsController_getRoomProfile", + "summary": "Get room profile by URL or subdomain", + "description": "Retrieve a room profile by its unique URL (for groups) or subdomain (for pages). Returns room details, member counts, and relationship status.", + "parameters": [ + { + "name": "url", + "required": false, + "in": "path", + "description": "Group URL identifier (lowercase)", + "schema": { "type": "string" } + }, + { + "name": "subdomain", + "required": false, + "in": "path", + "description": "Page subdomain identifier (lowercase)", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { + "description": "Room profile with details and membership info" + }, + "404": { "description": "Room not found" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/group/{url}/accept/{token}": { + "get": { + "operationId": "RoomsController_acceptByPrivateToken", + "summary": "Accept room invite by private token", + "description": "Accept an invitation using a private room URL with embedded token. Alternative to the /accept-invite endpoint for direct link access.", + "parameters": [ + { + "name": "url", + "required": false, + "in": "path", + "description": "Group URL identifier", + "schema": { "type": "string" } + }, + { + "name": "subdomain", + "required": false, + "in": "path", + "description": "Page subdomain identifier", + "schema": { "type": "string" } + }, + { + "name": "token", + "required": true, + "in": "path", + "description": "Private invitation token", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { "description": "Invitation accepted - user added to room" }, + "400": { "description": "Invalid or expired token" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/page/{subdomain}/accept/{token}": { + "get": { + "operationId": "RoomsController_acceptByPrivateToken", + "summary": "Accept room invite by private token", + "description": "Accept an invitation using a private room URL with embedded token. Alternative to the /accept-invite endpoint for direct link access.", + "parameters": [ + { + "name": "url", + "required": false, + "in": "path", + "description": "Group URL identifier", + "schema": { "type": "string" } + }, + { + "name": "subdomain", + "required": false, + "in": "path", + "description": "Page subdomain identifier", + "schema": { "type": "string" } + }, + { + "name": "token", + "required": true, + "in": "path", + "description": "Private invitation token", + "schema": { "type": "string" } + } + ], + "responses": { + "200": { "description": "Invitation accepted - user added to room" }, + "400": { "description": "Invalid or expired token" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{id}": { + "get": { + "operationId": "RoomsController_getRoomProfileById", + "summary": "Get room profile by ID", + "description": "Retrieve a room profile by its unique numeric ID. Returns room details, member counts, and relationship status for the current user.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { "description": "Room profile retrieved successfully" }, + "404": { "description": "Room not found" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{id}/posts": { + "get": { + "operationId": "RoomsController_getRoomPosts", + "summary": "Get room posts", + "description": "Retrieve paginated posts shared within a room. Supports filtering by tab (REFLECTIONS, DISCUSSIONS) and sorting (LATEST, POPULAR).", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + }, + { + "name": "sortBy", + "required": false, + "in": "query", + "description": "Sort order (default: latest)", + "schema": { "enum": ["latest", "popular"], "type": "string" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Posts per page (max: 20)", + "schema": { + "minimum": 1, + "maximum": 20, + "default": 20, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + }, + { + "name": "tab", + "required": false, + "in": "query", + "description": "Filter posts by content type", + "schema": { + "enum": ["reflections", "saved", "public", "members_only"], + "type": "string" + } + } + ], + "responses": { + "200": { "description": "Room posts with pagination" }, + "404": { "description": "Room not found" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{groupId}/join": { + "post": { + "operationId": "RoomsController_joinRoom", + "summary": "Join a group", + "description": "Join a public group as a member. For private groups, an invitation is required. Returns whether the join was successful.", + "parameters": [ + { + "name": "groupId", + "required": true, + "in": "path", + "description": "Unique numeric group ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Successfully joined the group", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "joined": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { "description": "Group is private - invitation required" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{groupId}/leave": { + "post": { + "operationId": "RoomsController_leaveGroup", + "summary": "Leave a group", + "description": "Leave a group the user is currently a member of. Owners cannot leave - they must transfer ownership first.", + "parameters": [ + { + "name": "groupId", + "required": true, + "in": "path", + "description": "Unique numeric group ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Successfully left the group", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "left": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { + "description": "Owner cannot leave - transfer ownership first" + } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{pageId}/follow": { + "post": { + "operationId": "RoomsController_followPage", + "summary": "Follow a page", + "description": "Follow an organizational page to see their posts in your feed. Pages represent verified organizations or scholars.", + "parameters": [ + { + "name": "pageId", + "required": true, + "in": "path", + "description": "Unique numeric page ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Successfully followed the page", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "followed": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{pageId}/unfollow": { + "post": { + "operationId": "RoomsController_unfollowPage", + "summary": "Unfollow a page", + "description": "Stop following a page. Their posts will no longer appear in your personalized feed.", + "parameters": [ + { + "name": "pageId", + "required": true, + "in": "path", + "description": "Unique numeric page ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Successfully unfollowed the page", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "unfollowed": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/rooms/{roomId}/posts/{postId}/privacy": { + "patch": { + "operationId": "RoomsController_updatePostPrivacy", + "summary": "Update post privacy in room", + "description": "Change the visibility of a post within a room. Toggle between public (visible outside room) and private (members only). Only admins can modify.", + "parameters": [ + { + "name": "roomId", + "required": true, + "in": "path", + "description": "Unique numeric room ID", + "schema": { "type": "number" } + }, + { + "name": "postId", + "required": true, + "in": "path", + "description": "Unique numeric post ID", + "schema": { "type": "number" } + } + ], + "requestBody": { + "required": true, + "description": "Privacy setting with isPublic boolean", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RoomPostUpdatePrivacyDto" + } + } + } + }, + "responses": { + "200": { "description": "Post privacy updated successfully" }, + "401": { "description": "User not authenticated" }, + "403": { + "description": "User not authorized to modify post privacy" + }, + "404": { "description": "Room or post not found" } + }, + "tags": ["Rooms"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/feed": { + "get": { + "operationId": "PostsController_feed", + "summary": "Get posts feed", + "description": "Retrieve a paginated feed of posts (reflections). Supports filtering by authors, tags, Quran references, groups, pages, and post types. Results can be filtered by language preferences from user settings or query parameters.", + "parameters": [ + { + "name": "tab", + "required": false, + "in": "query", + "description": "Feed tab type. feed shows personalized content, trending shows explore, following shows posts from followed users.", + "schema": { + "enum": [ + "newest", + "latest", + "following", + "draft", + "favorite", + "most_popular", + "only_room_members", + "public", + "feed", + "trending", + "popular" + ], + "type": "string" + } + }, + { + "name": "languages", + "required": false, + "in": "query", + "description": "Array of language IDs to filter posts by reflection language", + "schema": { "type": "array", "items": { "type": "number" } } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number for pagination (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Number of posts per page (default: 20)", + "schema": { "minimum": 1, "default": 20, "type": "number" } + }, + { + "required": false, + "name": "authors", + "in": "query", + "schema": { "type": "array", "items": { "type": "string" } } + }, + { + "required": false, + "name": "tags", + "in": "query", + "schema": { "type": "array", "items": { "type": "string" } } + }, + { + "required": false, + "name": "references", + "in": "query", + "schema": { + "type": "array", + "items": { "$ref": "#/components/schemas/ReferenceAttributes" } + } + }, + { + "required": false, + "name": "groups", + "in": "query", + "schema": { "type": "array", "items": { "type": "string" } } + }, + { + "required": false, + "name": "pages", + "in": "query", + "schema": { "type": "array", "items": { "type": "string" } } + }, + { + "required": false, + "name": "postTypeIds", + "in": "query", + "schema": { "type": "array", "items": { "type": "number" } } + }, + { + "required": false, + "name": "tagsOperator", + "in": "query", + "schema": { "enum": ["OR", "AND"], "type": "string" } + }, + { + "required": false, + "name": "referencesOperator", + "in": "query", + "schema": { "enum": ["OR", "AND"], "type": "string" } + }, + { + "required": false, + "name": "verifiedOnly", + "in": "query", + "schema": { "default": false, "type": "boolean" } + } + ], + "responses": { + "200": { + "description": "Feed retrieved successfully with paginated posts", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/FeedResponseDto" } + } + } + } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/my-posts": { + "get": { + "operationId": "PostsController_getLoggedinUserPosts", + "summary": "Get current user posts", + "description": "Retrieve posts created by the currently authenticated user. Supports filtering by tab (MY_REFLECTIONS, SAVED, DRAFTS), sorting options, and post type filtering.", + "parameters": [ + { + "name": "tab", + "required": false, + "in": "query", + "description": "Profile tab filter (default: my_reflections)", + "schema": { + "enum": ["my_reflections", "saved", "notes", "mentions"], + "type": "string" + } + }, + { + "name": "sortBy", + "required": false, + "in": "query", + "description": "Sort order for posts (default: latest)", + "schema": { "enum": ["latest", "popular"], "type": "string" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Number of posts per page (default: 20, max: 20)", + "schema": { + "minimum": 1, + "maximum": 20, + "default": 20, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number for pagination (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + }, + { + "name": "postTypeIds", + "required": false, + "in": "query", + "description": "Array of post type IDs to filter by", + "schema": { "type": "array", "items": { "type": "number" } } + } + ], + "responses": { + "200": { + "description": "User posts retrieved successfully with pagination metadata", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/FeedResponseDto" } + } + } + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/{id}": { + "get": { + "operationId": "PostsController_findOne", + "summary": "Get post by ID", + "description": "Retrieve a specific post by its unique numeric ID. Returns the full post with author details, tags, references, room information, and engagement metrics. Admins can view additional moderation details.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Post found and returned with all associated data", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/PostSerialized" } + } + } + }, + "404": { "description": "Post not found or has been deleted" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + }, + "delete": { + "operationId": "PostsController_delete", + "summary": "Delete post", + "description": "Soft-delete a post by marking it as removed. Only the post author or admins can delete posts. Related engagement counts (likes, comments, saves) update asynchronously via background jobs, so metrics may briefly lag.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID to delete", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Post deletion accepted and queued for processing", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { "description": "User not authorized to delete this post" }, + "404": { "description": "Post not found" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + }, + "patch": { + "operationId": "PostsController_edit", + "summary": "Edit post", + "description": "Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID to update", + "schema": { "type": "number" } + } + ], + "requestBody": { + "required": true, + "description": "Partial post data to update - only include fields to change", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/UpdatePostDto" } + } + } + }, + "responses": { + "200": { + "description": "Post updated successfully with the updated post data", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/PostCreatedResponse" } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { "description": "User not authorized to edit this post" }, + "404": { "description": "Post not found" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/viewed/{id}": { + "get": { + "operationId": "PostsController_viewTracking", + "summary": "Track post view", + "description": "Record that a post has been viewed by the current user (if authenticated). Used for analytics and engagement tracking. Does not require authentication but will track user-specific views when logged in.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "View tracked successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": true } + } + } + } + } + } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts": { + "post": { + "operationId": "PostsController_create", + "summary": "Create post", + "description": "Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Post creation payload containing the post object with body, references, mentions, and visibility settings", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/CreatePostBodyDto" } + } + } + }, + "responses": { + "201": { + "description": "Post created successfully", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/PostCreatedResponse" } + } + } + }, + "400": { + "description": "Invalid post data - body too short, invalid references, or invalid room post status" + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/{id}/report": { + "post": { + "operationId": "PostsController_reportAbuse", + "summary": "Report post abuse", + "description": "Report a post for moderation review. Provide a reason for the report to help moderators evaluate the content. Multiple reports on the same post may trigger automatic review.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID to report", + "schema": { "type": "number" } + } + ], + "requestBody": { + "required": true, + "description": "Report details including reason for flagging the content", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/ReportAbuseBodyDto" } + } + } + }, + "responses": { + "200": { + "description": "Report submitted successfully for moderation review", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "reported": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/user-posts/{id}": { + "get": { + "operationId": "PostsController_getUserPost", + "summary": "Get user posts", + "description": "Retrieve public posts created by a specific user. If viewing own posts while authenticated, returns all posts including drafts. Supports sorting and filtering by post type.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "UUID of the user whose posts to retrieve", + "schema": { "type": "string" } + }, + { + "name": "sortBy", + "required": false, + "in": "query", + "description": "Sort order for posts (default: latest)", + "schema": { "enum": ["latest", "popular"], "type": "string" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Number of posts per page (default: 20, max: 20)", + "schema": { + "minimum": 1, + "maximum": 20, + "default": 20, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number for pagination (default: 1)", + "schema": { "minimum": 1, "default": 1, "type": "number" } + }, + { + "name": "postTypeIds", + "required": false, + "in": "query", + "description": "Array of post type IDs to filter by", + "schema": { "type": "array", "items": { "type": "number" } } + } + ], + "responses": { + "200": { + "description": "User posts retrieved with pagination metadata", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/FeedResponseDto" } + } + } + } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/{id}/toggle-like": { + "post": { + "operationId": "PostsController_toggleLike", + "summary": "Toggle post like", + "description": "Toggle like status for a post. If already liked, removes the like. If not liked, adds a like. Updates the post like count and triggers notifications.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID to like/unlike", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Like status toggled - returns new state", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "liked": { + "type": "boolean", + "description": "true if now liked, false if now unliked" + } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "404": { "description": "Post not found" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/{id}/toggle-save": { + "post": { + "operationId": "PostsController_toggleSave", + "summary": "Toggle post save", + "description": "Toggle save/bookmark status for a post. Saved posts appear in the SAVED tab of the user profile for easy access later.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID to save/unsave", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Save status toggled - returns new state", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "saved": { + "type": "boolean", + "description": "true if now saved, false if now unsaved" + } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "404": { "description": "Post not found" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/{id}/comments": { + "get": { + "operationId": "PostsController_getComments", + "summary": "Get post comments", + "description": "Retrieve paginated top-level comments for a post. Use the replies endpoint to get nested replies for specific comments.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID", + "schema": { "type": "number" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Number of results to return", + "schema": { + "minimum": 1, + "maximum": 20, + "default": 20, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number", + "schema": { "minimum": 1, "default": 1, "type": "number" } + } + ], + "responses": { + "200": { + "description": "Comments retrieved with pagination metadata", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostCommentsResponse" + } + } + } + }, + "404": { "description": "Post not found" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/{id}/all-comments": { + "get": { + "operationId": "PostsController_getAllComment", + "summary": "Get all post comments", + "description": "Retrieve all comments for a post in a single request without pagination. Useful for displaying full comment threads or export scenarios.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric post ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "All comments returned with total count", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/PostAllCommentsResponse" + } + } + } + }, + "404": { "description": "Post not found" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/export/pdf": { + "post": { + "operationId": "PostsController_exportMultiplePosts", + "summary": "Export posts as PDF", + "description": "Generate a downloadable PDF document containing selected posts with their full content, Quran references, and author information. Ayah translations are rendered according to user language preferences.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Array of post IDs to include in the PDF export (minimum 1)", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/ExportPostsDto" } + } + } + }, + "responses": { + "200": { + "description": "PDF file generated and returned as binary attachment", + "content": { + "application/pdf": { + "schema": { "type": "string", "format": "binary" } + } + } + }, + "400": { + "description": "Invalid request - empty or invalid post IDs array" + }, + "401": { "description": "User not authenticated" }, + "404": { + "description": "No accessible posts found for the given IDs" + } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/count-within-range": { + "get": { + "operationId": "PostsController_getMyPostsCountWithinRange", + "summary": "Get posts count within range", + "description": "Count how many posts the current user has written for verses within a specified Quran verse range. Useful for reading goals and progress tracking.", + "parameters": [ + { + "name": "from", + "required": true, + "in": "query", + "description": "Start verse key in format chapter:verse (e.g., \"2:1\")", + "schema": { + "pattern": "VERSE_KEY_REGEX", + "example": "2:1", + "type": "string" + } + }, + { + "name": "to", + "required": true, + "in": "query", + "description": "End verse key in format chapter:verse (e.g., \"2:286\")", + "schema": { + "pattern": "VERSE_KEY_REGEX", + "example": "2:286", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Count of posts within the specified verse range", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { "count": { "type": "number", "example": 5 } } + } + } + } + }, + "400": { + "description": "Invalid verse range - malformed keys or from > to" + }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/posts/by-verse/{verseKey}": { + "get": { + "operationId": "PostsController_getMyPostsByVerse", + "summary": "Get posts by verse", + "description": "Retrieve all posts written by the current user for a specific Quran verse. Returns posts referencing the exact verse key.", + "parameters": [ + { + "name": "verseKey", + "required": true, + "in": "path", + "description": "Verse key in format chapter:verse", + "schema": { + "pattern": "VERSE_KEY_REGEX", + "example": "2:255", + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "User posts for the specified verse", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/FeedResponseDto" } + } + } + }, + "400": { "description": "Invalid verse key format" }, + "401": { "description": "User not authenticated" } + }, + "tags": ["Posts"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/tags": { + "get": { + "operationId": "TagsController_find", + "summary": "Search and retrieve tags", + "description": "Search for tags by query string. Returns paginated results matching the search term. Useful for tag autocomplete and discovery features.", + "parameters": [ + { + "name": "query", + "required": false, + "in": "query", + "description": "Search term", + "schema": { "type": "string" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Number of results to return", + "schema": { "type": "number" } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Tags matching search query with pagination", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { "$ref": "#/components/schemas/Tag" } + } + } + } + } + }, + "tags": ["Tags"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/comments": { + "post": { + "operationId": "CommentsController_create", + "summary": "Create a new comment", + "description": "Add a comment to a post or reply to an existing comment. Supports mentions and notifies the post author.", + "parameters": [], + "requestBody": { + "required": true, + "description": "Comment with postId and optional parentId", + "content": { + "application/json": { + "schema": { "$ref": "#/components/schemas/CreateCommentBody" } + } + } + }, + "responses": { + "201": { + "description": "Comment created", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateCommentResponse" + } + } + } + }, + "400": { + "description": "Invalid comment - empty body or invalid postId" + }, + "401": { "description": "User not authenticated" }, + "404": { "description": "Post or parent comment not found" } + }, + "tags": ["Comments"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/comments/{id}/delete": { + "get": { + "operationId": "CommentsController_deleteComment", + "summary": "Delete a comment", + "description": "Soft-delete a comment. Only the author or admins can delete. Replies remain visible with placeholder.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric comment ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Comment deleted", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "removed": { "type": "boolean", "example": true } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "403": { + "description": "User not authorized to delete this comment" + }, + "404": { "description": "Comment not found" } + }, + "tags": ["Comments"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/comments/{id}/toggle-like": { + "post": { + "operationId": "CommentsController_toggleLike", + "summary": "Toggle like/unlike a comment", + "description": "Toggle like status. If liked, removes like. Notifies comment author on new likes.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Unique numeric comment ID", + "schema": { "type": "number" } + } + ], + "responses": { + "200": { + "description": "Like toggled", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "liked": { + "type": "boolean", + "description": "true if liked, false if unliked" + } + } + } + } + } + }, + "401": { "description": "User not authenticated" }, + "404": { "description": "Comment not found" } + }, + "tags": ["Comments"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + }, + "/v1/comments/{id}/replies": { + "get": { + "operationId": "CommentsController_get", + "summary": "Get replies to a comment", + "description": "Retrieve paginated replies (nested comments) for a parent comment with author info.", + "parameters": [ + { + "name": "id", + "required": true, + "in": "path", + "description": "Parent comment ID", + "schema": { "type": "number" } + }, + { + "name": "limit", + "required": false, + "in": "query", + "description": "Number of results to return", + "schema": { + "minimum": 1, + "maximum": 20, + "default": 20, + "type": "number" + } + }, + { + "name": "page", + "required": false, + "in": "query", + "description": "Page number", + "schema": { "minimum": 1, "default": 1, "type": "number" } + } + ], + "responses": { + "200": { + "description": "Comment replies with pagination", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CommentRepliesResponse" + } + } + } + }, + "404": { "description": "Parent comment not found" } + }, + "tags": ["Comments"], + "servers": [ + { + "url": "https://apis-prelive.quran.foundation/quran-reflect", + "description": "Pre-production Server" + }, + { + "url": "https://apis.quran.foundation/quran-reflect", + "description": "Production Server" + } + ] + } + } + } +} From 0776d7a12ef5032bda086f7132493cf9cfc78329 Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Sun, 25 Jan 2026 18:57:40 +0700 Subject: [PATCH 2/9] update docs --- .../1.0.0/add-collection-bookmark.api.mdx | 4 +- .../1.0.0/add-collection.api.mdx | 4 +- .../1.0.0/add-user-bookmark.api.mdx | 4 +- .../1.0.0/comments-controller-create.api.mdx | 2 +- .../1.0.0/comments-controller-get.api.mdx | 2 +- .../1.0.0/create-a-goal.api.mdx | 4 +- .../1.0.0/delete-a-goal.api.mdx | 4 +- .../1.0.0/delete-bookmark.api.mdx | 4 +- .../delete-collection-bookmark-by-id.api.mdx | 4 +- .../1.0.0/delete-collection.api.mdx | 4 +- .../1.0.0/get-activity-days.api.mdx | 8 +- .../1.0.0/get-all-collection-items.api.mdx | 6 +- .../1.0.0/get-all-collections.api.mdx | 6 +- .../1.0.0/get-all-notes.api.mdx | 4 +- .../1.0.0/get-bookmark-collections.api.mdx | 6 +- .../1.0.0/get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../1.0.0/get-collection-items-by-id.api.mdx | 6 +- .../1.0.0/get-mutations.api.mdx | 8 +- .../1.0.0/get-notes-by-verse.api.mdx | 4 +- .../1.0.0/get-streaks.api.mdx | 6 +- .../1.0.0/get-todays-goal-plan.api.mdx | 4 +- .../1.0.0/get-user-bookmarks.api.mdx | 6 +- .../1.0.0/get-user-reading-sessions.api.mdx | 6 +- .../1.0.0/posts-controller-create.api.mdx | 4 +- .../1.0.0/posts-controller-edit.api.mdx | 4 +- .../1.0.0/posts-controller-feed.api.mdx | 2 +- .../1.0.0/posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../1.0.0/sync-local-mutations.api.mdx | 6 +- .../1.0.0/tags-controller-find.api.mdx | 2 +- .../1.0.0/update-a-goal.api.mdx | 4 +- .../add-collection-bookmark.api.mdx | 4 +- .../add-collection.api.mdx | 4 +- .../add-user-bookmark.api.mdx | 4 +- .../comments-controller-create.api.mdx | 2 +- .../comments-controller-get.api.mdx | 2 +- .../create-a-goal.api.mdx | 4 +- .../delete-a-goal.api.mdx | 4 +- .../delete-bookmark.api.mdx | 4 +- .../delete-collection-bookmark-by-id.api.mdx | 4 +- .../delete-collection.api.mdx | 4 +- .../get-activity-days.api.mdx | 8 +- .../get-all-collection-items.api.mdx | 6 +- .../get-all-collections.api.mdx | 6 +- .../get-all-notes.api.mdx | 4 +- .../get-bookmark-collections.api.mdx | 6 +- .../get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../get-collection-items-by-id.api.mdx | 6 +- .../get-mutations.api.mdx | 8 +- .../get-notes-by-verse.api.mdx | 4 +- .../get-streaks.api.mdx | 6 +- .../get-todays-goal-plan.api.mdx | 4 +- .../get-user-bookmarks.api.mdx | 6 +- .../get-user-reading-sessions.api.mdx | 6 +- .../posts-controller-create.api.mdx | 4 +- .../posts-controller-edit.api.mdx | 4 +- .../posts-controller-feed.api.mdx | 2 +- .../posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../sync-local-mutations.api.mdx | 6 +- .../tags-controller-find.api.mdx | 2 +- .../update-a-goal.api.mdx | 4 +- openAPI/user-related-apis/v1.json | 176 ++++++++++++------ 73 files changed, 263 insertions(+), 209 deletions(-) diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx index ca64800d..7eeff177 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkthm7ui0008r4jq9bmzc243"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmktoftfj0008o5jqb19e6771"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
              Path Parameters
              Query Parameters
              Request Body
                anyOf
              +
              Path Parameters
              Query Parameters
              Request Body
                anyOf
              Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx index 852fdb7a..fc3f8e48 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
              data object
            +
          Schema
            data object
          The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx index 8b6cb3db..b3c86811 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
          data object
        +
      Schema
        data object
      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx index 67ecdade..8d621d1c 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
      Schema
        comment object required
        author object
        avatarUrls object required
        mentions object[]
      • Array [
        • avatarUrls object required
      • ]
        • tags object[]
      • Array [
      • ]
      +
      Schema
        comment object required
        author object
        avatarUrls object required
        mentions object[]
      • Array [
        • avatarUrls object required
      • ]
        • tags object[]
      • Array [
      • ]
      Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx index d06b7819..b6465b7b 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
      Schema
        replies object[] required
      • Array [
        • author object
        avatarUrls object required
        mentions object[]
      • Array [
        • avatarUrls object required
      • ]
        • tags object[]
      • Array [
      • ]
      • ]
        • comment object required
        author object
        avatarUrls object required
        mentions object[]
      • Array [
        • avatarUrls object required
      • ]
        • tags object[]
      • Array [
      • ]
      +
      Schema
        replies object[] required
      • Array [
        • author object
        avatarUrls object required
        mentions object[]
      • Array [
        • avatarUrls object required
      • ]
        • tags object[]
      • Array [
      • ]
      • ]
        • comment object required
        author object
        avatarUrls object required
        mentions object[]
      • Array [
        • avatarUrls object required
      • ]
        • tags object[]
      • Array [
      • ]
      Parent comment not found diff --git a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx index d2d149de..b8bdd095 100644 --- a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
      Schema
        data object
      +
      Schema
        data object
      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx index e0b4a4dd..134dc39a 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
      Path Parameters
      Query Parameters
      Header Parameters
      +
      Path Parameters
      Query Parameters
      Header Parameters
      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx index 56913cf3..e5a43b0d 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkthm7rj0006r4jq3w04aolo"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmktoftdg0006o5jqeno8esu6"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
      Path Parameters
      Query Parameters
      +
      Path Parameters
      Query Parameters
      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx index b2daf219..1d55b541 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7uu000ar4jqhzbcdlql"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkthm7uu000br4jqc2ec5h49"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftft000ao5jq3w117kao"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmktoftft000bo5jq6rmwbg3t"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
      Path Parameters
      Query Parameters
      +
      Path Parameters
      Query Parameters
      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx index c3f07df8..9430dbe9 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7up0009r4jqfaqg4iha"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftfo0009o5jq4fjc4fq0"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
      Path Parameters
      Query Parameters
      +
      Path Parameters
      Query Parameters
      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx index 7a98f519..5acc2c23 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
      Query Parameters
      +
      Query Parameters
      Request has been handled successfully. -
      Schema
        data object[]
      • Array [
        • ranges object
        +
        Schema
          data object[]
        • Array [
          • ranges object
          The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
        • ]
          • pagination object
        +
      • ]
        • pagination object
      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx index 42fd78a3..6da9538c 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
      Query Parameters
      +
      Query Parameters
      Request has been handled successfully. -
      Schema
        data object[]
      • Array [
      • ]
        • pagination object
      +
      Schema
        data object[]
      • Array [
      • ]
        • pagination object
      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx index b7b193ec..5498e8b9 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
      Query Parameters
      +
      Query Parameters
      Request has been handled successfully. -
      Schema
        data object[]
      • Array [
      • ]
        • pagination object
      +
      Schema
        data object[]
      • Array [
      • ]
        • pagination object
      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx index 4b093ce9..afac50f1 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
    • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx index f189a3f3..bbf46401 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx index ac561174..a61b2db4 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx index a89a82c6..dd4205b5 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx index 2380d43d..e3dbeb9f 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkthm7vj000cr4jqdkfabg59"}},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmktoftgc000co5jqh64b2swt"}},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx index 8e3a6a81..11f132c9 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx @@ -5,7 +5,7 @@ description: "Get list of mutations that were applied to resources after a certa sidebar_label: "Get mutations" hide_title: true hide_table_of_contents: true -api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Get list of mutations that were applied to resources after a certain point in time. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. @@ -38,11 +38,11 @@ Response schema for get mutations endpoint Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true. -
  • Array [
    • data object
    +
  • Array [
    • data object
    The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. -
  • ]
    • +
  • ]
    • The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx index c5b6a148..bdbb8640 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx index fd3f4498..f171985d 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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 streak.","example":"cmkthm85f000fr4jq7l9khj0j"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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 streak.","example":"cmktoftnt000fo5jqhhjp17l0"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx index 48c8a5b2..e6c7c7c6 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx index 1d544ecb..fcffc5ab 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx index 495172f7..5e05a31a 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm84w000er4jq7r9u47p2"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftnd000eo5jqhbgi60xv"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx index 4030d313..c66f4e86 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:58.670Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:59.761Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx index e4aecc04..5c646859 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:58.670Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:59.761Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx index e6373fb9..2de737cd 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx index 40d64366..a453da56 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx index 264712c7..df1015fa 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx index 53d11e57..55b02f9b 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx index bc240cab..0278cb9e 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx index f1c792d1..0550d404 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx index 5cea55ea..4c981e8f 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx index 45f0d059..ed2729de 100644 --- a/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx @@ -5,7 +5,7 @@ description: "An endpoint to sync local mutations to the server." sidebar_label: "Sync local mutations" hide_title: true hide_table_of_contents: true -api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -42,11 +42,11 @@ Response schema for post mutations endpoint Array of mutations that were successfully applied on the server. -
  • Array [
    • data object
    +
  • Array [
    • data object
    The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. -
  • ]
    • +
  • ]
    • The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx index cbce4d8f..178c915b 100644 --- a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
    Schema
    • Array [
    • ]
    +
    Schema
    • Array [
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx index ad9bc24e..50071e38 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
    Path Parameters
    Query Parameters
    Header Parameters
    Request Body
      amount object
      +
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx index 350c0ffc..8d771cca 100644 --- a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkthm7ui0008r4jq9bmzc243"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmktoftfj0008o5jqb19e6771"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
        Path Parameters
        Query Parameters
        Request Body
          anyOf
        +
        Path Parameters
        Query Parameters
        Request Body
          anyOf
        Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/add-collection.api.mdx b/docs/user_related_apis_versioned/add-collection.api.mdx index 952605a0..990fa8d3 100644 --- a/docs/user_related_apis_versioned/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
        data object
      +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx index b51ed093..561885e5 100644 --- a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/comments-controller-create.api.mdx index 5b914cf1..32a87d00 100644 --- a/docs/user_related_apis_versioned/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/comments-controller-get.api.mdx index 43e8751b..ccde5511 100644 --- a/docs/user_related_apis_versioned/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Parent comment not found diff --git a/docs/user_related_apis_versioned/create-a-goal.api.mdx b/docs/user_related_apis_versioned/create-a-goal.api.mdx index dfaae198..93b45e98 100644 --- a/docs/user_related_apis_versioned/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/delete-a-goal.api.mdx index d8996ea4..b3bde8d7 100644 --- a/docs/user_related_apis_versioned/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
    Path Parameters
    Query Parameters
    Header Parameters
    +
    Path Parameters
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/delete-bookmark.api.mdx index 75bcc9c8..e3adb06d 100644 --- a/docs/user_related_apis_versioned/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkthm7rj0006r4jq3w04aolo"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmktoftdg0006o5jqeno8esu6"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx index 160ff0ac..72ff2cc4 100644 --- a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7uu000ar4jqhzbcdlql"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkthm7uu000br4jqc2ec5h49"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftft000ao5jq3w117kao"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmktoftft000bo5jq6rmwbg3t"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-collection.api.mdx b/docs/user_related_apis_versioned/delete-collection.api.mdx index 24e668c7..69f03531 100644 --- a/docs/user_related_apis_versioned/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkthm7up0009r4jqfaqg4iha"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftfo0009o5jq4fjc4fq0"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/get-activity-days.api.mdx b/docs/user_related_apis_versioned/get-activity-days.api.mdx index 43df28b7..5ed94afd 100644 --- a/docs/user_related_apis_versioned/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
      • ranges object
      +
      Schema
        data object[]
      • Array [
        • ranges object
        The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
      • ]
        • pagination object
      +
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx index 7febad75..876a3df9 100644 --- a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collections.api.mdx b/docs/user_related_apis_versioned/get-all-collections.api.mdx index 75560a7f..ecede24d 100644 --- a/docs/user_related_apis_versioned/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-notes.api.mdx b/docs/user_related_apis_versioned/get-all-notes.api.mdx index aec48f00..d85e128b 100644 --- a/docs/user_related_apis_versioned/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx index b332d71d..3cb3ddbf 100644 --- a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark.api.mdx b/docs/user_related_apis_versioned/get-bookmark.api.mdx index c57fb695..b6812e8e 100644 --- a/docs/user_related_apis_versioned/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx index 7a745d72..fd1a7908 100644 --- a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx index eba85733..9a481a08 100644 --- a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkthm7vj000cr4jqdkfabg59"}},{"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7sk0007r4jq6spyau75"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmktoftgc000co5jqh64b2swt"}},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-mutations.api.mdx b/docs/user_related_apis_versioned/get-mutations.api.mdx index 5b282e98..8c92eb0e 100644 --- a/docs/user_related_apis_versioned/get-mutations.api.mdx +++ b/docs/user_related_apis_versioned/get-mutations.api.mdx @@ -5,7 +5,7 @@ description: "Get list of mutations that were applied to resources after a certa sidebar_label: "Get mutations" hide_title: true hide_table_of_contents: true -api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Get list of mutations that were applied to resources after a certain point in time. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. @@ -38,11 +38,11 @@ Response schema for get mutations endpoint Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true. -
  • Array [
    • data object
    +
  • Array [
    • data object
    The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. -
  • ]
    • +
  • ]
    • The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx index 6809605b..f5c98935 100644 --- a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-streaks.api.mdx b/docs/user_related_apis_versioned/get-streaks.api.mdx index 5633490d..ec8f9846 100644 --- a/docs/user_related_apis_versioned/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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 streak.","example":"cmkthm85f000fr4jq7l9khj0j"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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 streak.","example":"cmktoftnt000fo5jqhhjp17l0"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx index ecabfd4c..b7efec51 100644 --- a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkthm7ms0004r4jq82u23hpc"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx index 2cec3820..6aed0f39 100644 --- a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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":"object","properties":{"id":{"type":"string","example":"cmkthm7rb0005r4jq3r20ge06"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx index f4c2af65..a16bedb3 100644 --- a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmkthm7m70000r4jq8fv86xcq"},"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":"cmkthm7m70001r4jqfl9j81bv"},"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","example":"cmkthm84w000er4jq7r9u47p2"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkthm7m70002r4jqbbxjavgq"},"endCursor":{"type":"string","example":"cmkthm7m70003r4jqatt3c580"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftnd000eo5jqhbgi60xv"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/posts-controller-create.api.mdx index e07b7088..3d6661fe 100644 --- a/docs/user_related_apis_versioned/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:55.098Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:56.613Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx index 7ff34bba..abd488c6 100644 --- a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T08:39:55.098Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:56.613Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx index 9be873f4..b250e836 100644 --- a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx index bfb42ed9..a3135dab 100644 --- a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx index 4f2ce7bb..b03ce218 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx index 653286da..44bef385 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx index d979658f..93856ded 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx index 0fc40e36..01add187 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx index 0c2a6eb3..723a5bec 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx index 45e80fd2..4d4a6889 100644 --- a/docs/user_related_apis_versioned/sync-local-mutations.api.mdx +++ b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx @@ -5,7 +5,7 @@ description: "An endpoint to sync local mutations to the server." sidebar_label: "Sync local mutations" hide_title: true hide_table_of_contents: true -api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1731636500303}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync/","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync",""],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -42,11 +42,11 @@ Response schema for post mutations endpoint Array of mutations that were successfully applied on the server. -
  • Array [
    • data object
    +
  • Array [
    • data object
    The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete. -
  • ]
    • +
  • ]
    • The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/tags-controller-find.api.mdx index 150e9989..6a4d1d46 100644 --- a/docs/user_related_apis_versioned/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
    Schema
    • Array [
    • ]
    +
    Schema
    • Array [
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/update-a-goal.api.mdx b/docs/user_related_apis_versioned/update-a-goal.api.mdx index 00894220..5d7e2bda 100644 --- a/docs/user_related_apis_versioned/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkthm7wi000dr4jq0w3geidl"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
    Path Parameters
    Query Parameters
    Header Parameters
    Request Body
      amount object
      +
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/openAPI/user-related-apis/v1.json b/openAPI/user-related-apis/v1.json index dc6f6e38..2bb60fe3 100644 --- a/openAPI/user-related-apis/v1.json +++ b/openAPI/user-related-apis/v1.json @@ -34,7 +34,7 @@ "Bookmark": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmkthm7rb0005r4jq3r20ge06" }, + "id": { "type": "string", "example": "cmktoftda0005o5jq3i7garfu" }, "createdAt": { "type": "string", "format": "date-time", @@ -51,7 +51,7 @@ "Collection": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmkthm7sk0007r4jq6spyau75" }, + "id": { "type": "string", "example": "cmktofte80007o5jqfpdy2vr0" }, "updatedAt": { "type": "string", "format": "date-time", @@ -357,7 +357,7 @@ "ReadingSession": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmkthm84w000er4jq7r9u47p2" }, + "id": { "type": "string", "example": "cmktoftnd000eo5jqhbgi60xv" }, "updatedAt": { "type": "string", "format": "date-time", @@ -1447,7 +1447,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -1458,7 +1458,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -1481,11 +1481,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -1718,7 +1718,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be added.", - "example": "cmkthm7ui0008r4jq9bmzc243" + "example": "cmktoftfj0008o5jqb19e6771" }, "required": true, "description": "The Id of the collection to be added." @@ -2041,7 +2041,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmkthm7up0009r4jqfaqg4iha" + "example": "cmktoftfo0009o5jq4fjc4fq0" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2301,7 +2301,7 @@ "name": "collectionId", "schema": { "type": "string", - "example": "cmkthm7vj000cr4jqdkfabg59" + "example": "cmktoftgc000co5jqh64b2swt" } }, { @@ -2346,7 +2346,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -2357,7 +2357,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -2389,11 +2389,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -2903,7 +2903,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmkthm7uu000ar4jqhzbcdlql" + "example": "cmktoftft000ao5jq3w117kao" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2914,7 +2914,7 @@ "schema": { "type": "string", "description": "The Id of the bookmark to be deleted.", - "example": "cmkthm7uu000br4jqc2ec5h49" + "example": "cmktoftft000bo5jq6rmwbg3t" }, "required": true, "description": "The Id of the bookmark to be deleted." @@ -3224,7 +3224,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -3235,7 +3235,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -3258,11 +3258,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -3855,7 +3855,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -3867,7 +3867,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -3891,11 +3891,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -4128,7 +4128,7 @@ "schema": { "type": "string", "description": "The id of the bookmark to be deleted.", - "example": "cmkthm7rj0006r4jq3w04aolo" + "example": "cmktoftdg0006o5jqeno8esu6" }, "required": true, "description": "The id of the bookmark to be deleted." @@ -4446,11 +4446,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -5019,7 +5019,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -5031,7 +5031,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -6683,7 +6683,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -6694,7 +6694,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -6717,11 +6717,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -7004,7 +7004,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmkthm7ms0004r4jq82u23hpc" + "example": "cmktoft9r0004o5jq0bxt841p" }, "date": { "type": "string", @@ -7352,7 +7352,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmkthm7wi000dr4jq0w3geidl" + "example": "cmktofth3000do5jqamxbg7jq" }, "required": true, "description": "The id of the goal." @@ -7666,7 +7666,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmkthm7wi000dr4jq0w3geidl" + "example": "cmktofth3000do5jqamxbg7jq" }, "required": true, "description": "The id of the goal." @@ -8014,7 +8014,7 @@ "id": { "type": "string", "description": "The id of the goal.", - "example": "cmkthm7wi000dr4jq0w3geidl" + "example": "cmktofth3000do5jqamxbg7jq" } }, "required": ["id"], @@ -8641,7 +8641,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -8652,7 +8652,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -8674,7 +8674,7 @@ "id": { "type": "string", "description": "The id of the streak.", - "example": "cmkthm85f000fr4jq7l9khj0j" + "example": "cmktoftnt000fo5jqhhjp17l0" }, "startDate": { "type": "string", @@ -8715,11 +8715,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -9581,7 +9581,7 @@ "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": "cmkthm7m70000r4jq8fv86xcq" + "example": "cmktoft9b0000o5jqbbyn87s0" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -9592,7 +9592,7 @@ "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": "cmkthm7m70001r4jqfl9j81bv" + "example": "cmktoft9b0001o5jq5ry99m3s" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -9614,7 +9614,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmkthm7ms0004r4jq82u23hpc" + "example": "cmktoft9r0004o5jq0bxt841p" }, "date": { "type": "string", @@ -9738,11 +9738,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -10466,11 +10466,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -11174,11 +11174,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkthm7m70002r4jqbbxjavgq" + "example": "cmktoft9c0002o5jq48yvcs24" }, "endCursor": { "type": "string", - "example": "cmkthm7m70003r4jqatt3c580" + "example": "cmktoft9c0003o5jqgiwk0pej" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -13531,7 +13531,7 @@ } } }, - "/v1/sync/": { + "/v1/sync": { "get": { "description": "Get list of mutations that were applied to resources after a certain point in time.", "tags": ["Sync"], @@ -13554,11 +13554,11 @@ "name": "resources", "schema": { "type": "string", - "description": "Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned.", - "example": "BOOKMARK,COLLECTION" + "description": "Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.", + "example": "BOOKMARK,COLLECTION,COLLECTION_BOOKMARK" }, "required": false, - "description": "Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION\"). If not provided, all accessible resources will be returned." + "description": "Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned." }, { "in": "query", @@ -13638,7 +13638,7 @@ }, "resourceId": { "type": "string", - "description": "The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.", + "description": "The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).", "example": "lqc794i0qnxq4pdlfanfbd2r" }, "data": { @@ -13668,14 +13668,41 @@ { "type": "CREATE", "resource": "BOOKMARK", - "resourceId": "lqc794i0qnxq4pdlfanfbd2r", + "resourceId": "u54maufl0ftmarp73ei0hg64", "data": { "bookmarkType": "ayah", "bookmarkGroup": "verses_6236", "key": 6, "verseNumber": 3 }, - "timestamp": 1731636500303 + "timestamp": 1769340915572 + }, + { + "type": "UPDATE", + "resource": "COLLECTION", + "resourceId": "na6orcv0pbcomiphmkv0yhma", + "data": { + "name": "New collection!", + "slug": "new-collection", + "isPrivate": true + }, + "timestamp": 1769340915572 + }, + { + "type": "CREATE", + "resource": "COLLECTION_BOOKMARK", + "data": { + "collection": "na6orcv0pbcomiphmkv0yhma", + "bookmark": "u54maufl0ftmarp73ei0hg64" + }, + "timestamp": 1769340915575 + }, + { + "type": "DELETE", + "resource": "NOTE", + "resourceId": "his2lubkxxr3l102nqptmnur", + "data": {}, + "timestamp": 1769341113173 } ] }, @@ -14034,7 +14061,7 @@ }, "resourceId": { "type": "string", - "description": "The id of the resource the mutation was applied to. Will not be present if the mutation was applied to certain resource without specific ID e.g. Preference.", + "description": "The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).", "example": "lqc794i0qnxq4pdlfanfbd2r" }, "data": { @@ -14064,14 +14091,41 @@ { "type": "CREATE", "resource": "BOOKMARK", - "resourceId": "lqc794i0qnxq4pdlfanfbd2r", + "resourceId": "u54maufl0ftmarp73ei0hg64", "data": { "bookmarkType": "ayah", "bookmarkGroup": "verses_6236", "key": 6, "verseNumber": 3 }, - "timestamp": 1731636500303 + "timestamp": 1769340915572 + }, + { + "type": "UPDATE", + "resource": "COLLECTION", + "resourceId": "na6orcv0pbcomiphmkv0yhma", + "data": { + "name": "New collection!", + "slug": "new-collection", + "isPrivate": true + }, + "timestamp": 1769340915572 + }, + { + "type": "CREATE", + "resource": "COLLECTION_BOOKMARK", + "data": { + "collection": "na6orcv0pbcomiphmkv0yhma", + "bookmark": "u54maufl0ftmarp73ei0hg64" + }, + "timestamp": 1769340915575 + }, + { + "type": "DELETE", + "resource": "NOTE", + "resourceId": "his2lubkxxr3l102nqptmnur", + "data": {}, + "timestamp": 1769341113173 } ] }, From c249dac07fab8d0659bd6c5b6e796a1f15480eb9 Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Mon, 26 Jan 2026 01:34:49 +0700 Subject: [PATCH 3/9] update docs --- .../1.0.0/add-collection-bookmark.api.mdx | 4 +- .../1.0.0/add-collection.api.mdx | 4 +- .../1.0.0/add-user-bookmark.api.mdx | 4 +- .../1.0.0/comments-controller-create.api.mdx | 2 +- .../1.0.0/comments-controller-get.api.mdx | 2 +- .../1.0.0/create-a-goal.api.mdx | 4 +- .../1.0.0/delete-a-goal.api.mdx | 4 +- .../1.0.0/delete-bookmark.api.mdx | 4 +- .../delete-collection-bookmark-by-id.api.mdx | 4 +- .../1.0.0/delete-collection.api.mdx | 4 +- .../1.0.0/get-activity-days.api.mdx | 8 +- .../1.0.0/get-all-collection-items.api.mdx | 6 +- .../1.0.0/get-all-collections.api.mdx | 6 +- .../1.0.0/get-all-notes.api.mdx | 4 +- .../1.0.0/get-bookmark-collections.api.mdx | 6 +- .../1.0.0/get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../1.0.0/get-collection-items-by-id.api.mdx | 6 +- .../1.0.0/get-mutations.api.mdx | 8 +- .../1.0.0/get-notes-by-verse.api.mdx | 4 +- .../1.0.0/get-streaks.api.mdx | 6 +- .../1.0.0/get-todays-goal-plan.api.mdx | 4 +- .../1.0.0/get-user-bookmarks.api.mdx | 6 +- .../1.0.0/get-user-reading-sessions.api.mdx | 6 +- .../1.0.0/posts-controller-create.api.mdx | 4 +- .../1.0.0/posts-controller-edit.api.mdx | 4 +- .../1.0.0/posts-controller-feed.api.mdx | 2 +- .../1.0.0/posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../1.0.0/sync-local-mutations.api.mdx | 8 +- .../1.0.0/tags-controller-find.api.mdx | 2 +- .../1.0.0/update-a-goal.api.mdx | 4 +- .../add-collection-bookmark.api.mdx | 4 +- .../add-collection.api.mdx | 4 +- .../add-user-bookmark.api.mdx | 4 +- .../comments-controller-create.api.mdx | 2 +- .../comments-controller-get.api.mdx | 2 +- .../create-a-goal.api.mdx | 4 +- .../delete-a-goal.api.mdx | 4 +- .../delete-bookmark.api.mdx | 4 +- .../delete-collection-bookmark-by-id.api.mdx | 4 +- .../delete-collection.api.mdx | 4 +- .../get-activity-days.api.mdx | 8 +- .../get-all-collection-items.api.mdx | 6 +- .../get-all-collections.api.mdx | 6 +- .../get-all-notes.api.mdx | 4 +- .../get-bookmark-collections.api.mdx | 6 +- .../get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../get-collection-items-by-id.api.mdx | 6 +- .../get-mutations.api.mdx | 8 +- .../get-notes-by-verse.api.mdx | 4 +- .../get-streaks.api.mdx | 6 +- .../get-todays-goal-plan.api.mdx | 4 +- .../get-user-bookmarks.api.mdx | 6 +- .../get-user-reading-sessions.api.mdx | 6 +- .../posts-controller-create.api.mdx | 4 +- .../posts-controller-edit.api.mdx | 4 +- .../posts-controller-feed.api.mdx | 2 +- .../posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../sync-local-mutations.api.mdx | 8 +- .../tags-controller-find.api.mdx | 2 +- .../update-a-goal.api.mdx | 4 +- openAPI/user-related-apis/v1.json | 114 ++++++++++-------- 73 files changed, 221 insertions(+), 193 deletions(-) diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx index 7eeff177..9d82db98 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmktoftfj0008o5jqb19e6771"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmku2pw240008pdjqhq5r6or3"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
        Path Parameters
        Query Parameters
        Request Body
          anyOf
        +
        Path Parameters
        Query Parameters
        Request Body
          anyOf
        Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx index fc3f8e48..a2ea8421 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
        data object
      +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx index b3c86811..b24fd21a 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx index 8d621d1c..302d9b28 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx index b6465b7b..5236685b 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Parent comment not found diff --git a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx index b8bdd095..2d936714 100644 --- a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx index 134dc39a..23d9d26a 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
    Path Parameters
    Query Parameters
    Header Parameters
    +
    Path Parameters
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx index e5a43b0d..c361c96b 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmktoftdg0006o5jqeno8esu6"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmku2pvzi0006pdjq9cai8zg8"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx index 1d55b541..c084b291 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftft000ao5jq3w117kao"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmktoftft000bo5jq6rmwbg3t"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2i000apdjqae7igz3n"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmku2pw2i000bpdjqeuau0kl3"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx index 9430dbe9..97f9b35f 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftfo0009o5jq4fjc4fq0"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2b0009pdjq26tddi7u"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx index 5acc2c23..2a8e8466 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
      • ranges object
      +
      Schema
        data object[]
      • Array [
        • ranges object
        The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
      • ]
        • pagination object
      +
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx index 6da9538c..a53da869 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx index 5498e8b9..59aa9185 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx index afac50f1..92c35447 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx index bbf46401..081f484d 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx index a61b2db4..bbb23724 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx index dd4205b5..dcd4626b 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx index e3dbeb9f..3fb785d6 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmktoftgc000co5jqh64b2swt"}},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmku2pw36000cpdjqfahw9b56"}},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx index 11f132c9..4c2844f4 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx @@ -5,7 +5,7 @@ description: "Get list of mutations that were applied to resources after a certa sidebar_label: "Get mutations" hide_title: true hide_table_of_contents: true -api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":false}}},"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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,11 @@ Get list of mutations that were applied to resources after a certain point in ti Request has been handled successfully. -
    Schema
      data object
      +
      Response Headers
      • X-Mutation-At string
        + +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
        data object
        Response schema for get mutations endpoint diff --git a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx index bdbb8640..51110092 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
      • ]
    • ]
    pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx index f171985d..f3720bb6 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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 streak.","example":"cmktoftnt000fo5jqhhjp17l0"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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 streak.","example":"cmku2pwch000fpdjqbtmhe78f"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx index e6c7c7c6..7b7f6200 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx index fcffc5ab..7aee1569 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx index 5e05a31a..088abc50 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftnd000eo5jqhbgi60xv"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pwby000epdjqg6eqec02"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx index c66f4e86..7e93d7d8 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:59.761Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:33.823Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx index 5c646859..1c2a909f 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:59.761Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:33.823Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx index 2de737cd..d4bdb4a9 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx index a453da56..2d61a02e 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx index df1015fa..d587149d 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx index 55b02f9b..5bc2a5b7 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx index 0278cb9e..77bcd283 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx index 0550d404..c41dd13e 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx index 4c981e8f..f0d0e5eb 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx index ed2729de..066811e2 100644 --- a/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx @@ -5,7 +5,7 @@ description: "An endpoint to sync local mutations to the server." sidebar_label: "Sync local mutations" hide_title: true hide_table_of_contents: true -api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,11 @@ Resource data. Format depends on resource type. Request has been handled successfully. -
    Schema
      data object
      +
      Response Headers
      • X-Mutation-At string
        + +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
        data object
        Response schema for post mutations endpoint diff --git a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx index 178c915b..5768e9ec 100644 --- a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
        Schema
        • Array [
        • ]
        +
      Schema
      • Array [
      • ]
      \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx index 50071e38..1125b0d5 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        +
        Path Parameters
        Query Parameters
        Header Parameters
        Request Body
          amount object
          The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx index 8d771cca..e98387fc 100644 --- a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmktoftfj0008o5jqb19e6771"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmku2pw240008pdjqhq5r6or3"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
          Path Parameters
          Query Parameters
          Request Body
            anyOf
          +
          Path Parameters
          Query Parameters
          Request Body
            anyOf
          Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/add-collection.api.mdx b/docs/user_related_apis_versioned/add-collection.api.mdx index 990fa8d3..f54ffcd4 100644 --- a/docs/user_related_apis_versioned/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
          data object
        +
      Schema
        data object
      The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx index 561885e5..9d3abf5f 100644 --- a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/comments-controller-create.api.mdx index 32a87d00..ef7620cc 100644 --- a/docs/user_related_apis_versioned/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/comments-controller-get.api.mdx index ccde5511..f254407e 100644 --- a/docs/user_related_apis_versioned/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Parent comment not found diff --git a/docs/user_related_apis_versioned/create-a-goal.api.mdx b/docs/user_related_apis_versioned/create-a-goal.api.mdx index 93b45e98..58d2f01f 100644 --- a/docs/user_related_apis_versioned/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/delete-a-goal.api.mdx index b3bde8d7..c0ec306b 100644 --- a/docs/user_related_apis_versioned/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
    Path Parameters
    Query Parameters
    Header Parameters
    +
    Path Parameters
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/delete-bookmark.api.mdx index e3adb06d..39ce7e5f 100644 --- a/docs/user_related_apis_versioned/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmktoftdg0006o5jqeno8esu6"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmku2pvzi0006pdjq9cai8zg8"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx index 72ff2cc4..4974a094 100644 --- a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftft000ao5jq3w117kao"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmktoftft000bo5jq6rmwbg3t"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2i000apdjqae7igz3n"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmku2pw2i000bpdjqeuau0kl3"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-collection.api.mdx b/docs/user_related_apis_versioned/delete-collection.api.mdx index 69f03531..4ee0b19f 100644 --- a/docs/user_related_apis_versioned/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmktoftfo0009o5jq4fjc4fq0"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2b0009pdjq26tddi7u"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/get-activity-days.api.mdx b/docs/user_related_apis_versioned/get-activity-days.api.mdx index 5ed94afd..2c2e36d0 100644 --- a/docs/user_related_apis_versioned/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
      • ranges object
      +
      Schema
        data object[]
      • Array [
        • ranges object
        The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
      • ]
        • pagination object
      +
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx index 876a3df9..af642eab 100644 --- a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collections.api.mdx b/docs/user_related_apis_versioned/get-all-collections.api.mdx index ecede24d..f23eab13 100644 --- a/docs/user_related_apis_versioned/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-notes.api.mdx b/docs/user_related_apis_versioned/get-all-notes.api.mdx index d85e128b..a94daeb9 100644 --- a/docs/user_related_apis_versioned/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx index 3cb3ddbf..2b373111 100644 --- a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark.api.mdx b/docs/user_related_apis_versioned/get-bookmark.api.mdx index b6812e8e..646e6d6a 100644 --- a/docs/user_related_apis_versioned/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx index fd1a7908..ca6c6ff9 100644 --- a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx index 9a481a08..735ef281 100644 --- a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmktoftgc000co5jqh64b2swt"}},{"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmktofte80007o5jqfpdy2vr0"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmku2pw36000cpdjqfahw9b56"}},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-mutations.api.mdx b/docs/user_related_apis_versioned/get-mutations.api.mdx index 8c92eb0e..92ca3797 100644 --- a/docs/user_related_apis_versioned/get-mutations.api.mdx +++ b/docs/user_related_apis_versioned/get-mutations.api.mdx @@ -5,7 +5,7 @@ description: "Get list of mutations that were applied to resources after a certa sidebar_label: "Get mutations" hide_title: true hide_table_of_contents: true -api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":false}}},"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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,11 @@ Get list of mutations that were applied to resources after a certain point in ti Request has been handled successfully. -
    Schema
      data object
      +
      Response Headers
      • X-Mutation-At string
        + +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
        data object
        Response schema for get mutations endpoint diff --git a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx index f5c98935..ecef1d02 100644 --- a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
      • ]
    • ]
    pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-streaks.api.mdx b/docs/user_related_apis_versioned/get-streaks.api.mdx index ec8f9846..39c7e72e 100644 --- a/docs/user_related_apis_versioned/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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 streak.","example":"cmktoftnt000fo5jqhhjp17l0"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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 streak.","example":"cmku2pwch000fpdjqbtmhe78f"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx index b7efec51..d12a3673 100644 --- a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmktoft9r0004o5jq0bxt841p"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx index 6aed0f39..7c608981 100644 --- a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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":"object","properties":{"id":{"type":"string","example":"cmktoftda0005o5jq3i7garfu"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx index a16bedb3..44b7ec8a 100644 --- a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmktoft9b0000o5jqbbyn87s0"},"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":"cmktoft9b0001o5jq5ry99m3s"},"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","example":"cmktoftnd000eo5jqhbgi60xv"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmktoft9c0002o5jq48yvcs24"},"endCursor":{"type":"string","example":"cmktoft9c0003o5jqgiwk0pej"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pwby000epdjqg6eqec02"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/posts-controller-create.api.mdx index 3d6661fe..8a2259c0 100644 --- a/docs/user_related_apis_versioned/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:56.613Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:30.634Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx index abd488c6..a6bae1f7 100644 --- a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T11:50:56.613Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:30.634Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx index b250e836..2c4cc68c 100644 --- a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx index a3135dab..54141cac 100644 --- a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx index b03ce218..a052a793 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx index 44bef385..a6e535e8 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx index 93856ded..80948c4e 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx index 01add187..b669c73e 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx index 723a5bec..1e29eca2 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx index 4d4a6889..31d0d487 100644 --- a/docs/user_related_apis_versioned/sync-local-mutations.api.mdx +++ b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx @@ -5,7 +5,7 @@ description: "An endpoint to sync local mutations to the server." sidebar_label: "Sync local mutations" hide_title: true hide_table_of_contents: true -api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,11 @@ Resource data. Format depends on resource type. Request has been handled successfully. -
    Schema
      data object
      +
      Response Headers
      • X-Mutation-At string
        + +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
        data object
        Response schema for post mutations endpoint diff --git a/docs/user_related_apis_versioned/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/tags-controller-find.api.mdx index 6a4d1d46..1f4e47fa 100644 --- a/docs/user_related_apis_versioned/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
        Schema
        • Array [
        • ]
        +
      Schema
      • Array [
      • ]
      \ No newline at end of file diff --git a/docs/user_related_apis_versioned/update-a-goal.api.mdx b/docs/user_related_apis_versioned/update-a-goal.api.mdx index 5d7e2bda..3568322e 100644 --- a/docs/user_related_apis_versioned/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmktofth3000do5jqamxbg7jq"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        +
        Path Parameters
        Query Parameters
        Header Parameters
        Request Body
          amount object
          The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/openAPI/user-related-apis/v1.json b/openAPI/user-related-apis/v1.json index 2bb60fe3..7cd9ea47 100644 --- a/openAPI/user-related-apis/v1.json +++ b/openAPI/user-related-apis/v1.json @@ -34,7 +34,7 @@ "Bookmark": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmktoftda0005o5jq3i7garfu" }, + "id": { "type": "string", "example": "cmku2pvz90005pdjq1l2ndb81" }, "createdAt": { "type": "string", "format": "date-time", @@ -51,7 +51,7 @@ "Collection": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmktofte80007o5jqfpdy2vr0" }, + "id": { "type": "string", "example": "cmku2pw0h0007pdjqc10s2chz" }, "updatedAt": { "type": "string", "format": "date-time", @@ -357,7 +357,7 @@ "ReadingSession": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmktoftnd000eo5jqhbgi60xv" }, + "id": { "type": "string", "example": "cmku2pwby000epdjqg6eqec02" }, "updatedAt": { "type": "string", "format": "date-time", @@ -1447,7 +1447,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -1458,7 +1458,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -1481,11 +1481,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -1718,7 +1718,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be added.", - "example": "cmktoftfj0008o5jqb19e6771" + "example": "cmku2pw240008pdjqhq5r6or3" }, "required": true, "description": "The Id of the collection to be added." @@ -2041,7 +2041,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmktoftfo0009o5jq4fjc4fq0" + "example": "cmku2pw2b0009pdjq26tddi7u" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2301,7 +2301,7 @@ "name": "collectionId", "schema": { "type": "string", - "example": "cmktoftgc000co5jqh64b2swt" + "example": "cmku2pw36000cpdjqfahw9b56" } }, { @@ -2346,7 +2346,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -2357,7 +2357,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -2389,11 +2389,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -2903,7 +2903,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmktoftft000ao5jq3w117kao" + "example": "cmku2pw2i000apdjqae7igz3n" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2914,7 +2914,7 @@ "schema": { "type": "string", "description": "The Id of the bookmark to be deleted.", - "example": "cmktoftft000bo5jq6rmwbg3t" + "example": "cmku2pw2i000bpdjqeuau0kl3" }, "required": true, "description": "The Id of the bookmark to be deleted." @@ -3224,7 +3224,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -3235,7 +3235,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -3258,11 +3258,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -3855,7 +3855,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -3867,7 +3867,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -3891,11 +3891,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -4128,7 +4128,7 @@ "schema": { "type": "string", "description": "The id of the bookmark to be deleted.", - "example": "cmktoftdg0006o5jqeno8esu6" + "example": "cmku2pvzi0006pdjq9cai8zg8" }, "required": true, "description": "The id of the bookmark to be deleted." @@ -4446,11 +4446,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -5019,7 +5019,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -5031,7 +5031,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -6683,7 +6683,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -6694,7 +6694,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -6717,11 +6717,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -7004,7 +7004,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmktoft9r0004o5jq0bxt841p" + "example": "cmku2pvv00004pdjqb000bm4m" }, "date": { "type": "string", @@ -7352,7 +7352,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmktofth3000do5jqamxbg7jq" + "example": "cmku2pw4c000dpdjq8fb6hiz4" }, "required": true, "description": "The id of the goal." @@ -7666,7 +7666,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmktofth3000do5jqamxbg7jq" + "example": "cmku2pw4c000dpdjq8fb6hiz4" }, "required": true, "description": "The id of the goal." @@ -8014,7 +8014,7 @@ "id": { "type": "string", "description": "The id of the goal.", - "example": "cmktofth3000do5jqamxbg7jq" + "example": "cmku2pw4c000dpdjq8fb6hiz4" } }, "required": ["id"], @@ -8641,7 +8641,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -8652,7 +8652,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -8674,7 +8674,7 @@ "id": { "type": "string", "description": "The id of the streak.", - "example": "cmktoftnt000fo5jqhhjp17l0" + "example": "cmku2pwch000fpdjqbtmhe78f" }, "startDate": { "type": "string", @@ -8715,11 +8715,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -9581,7 +9581,7 @@ "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": "cmktoft9b0000o5jqbbyn87s0" + "example": "cmku2pvui0000pdjqec4ug7py" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -9592,7 +9592,7 @@ "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": "cmktoft9b0001o5jq5ry99m3s" + "example": "cmku2pvuj0001pdjqgbvqbbqw" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -9614,7 +9614,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmktoft9r0004o5jq0bxt841p" + "example": "cmku2pvv00004pdjqb000bm4m" }, "date": { "type": "string", @@ -9738,11 +9738,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -10466,11 +10466,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -11174,11 +11174,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmktoft9c0002o5jq48yvcs24" + "example": "cmku2pvuj0002pdjqei7wcrwp" }, "endCursor": { "type": "string", - "example": "cmktoft9c0003o5jqgiwk0pej" + "example": "cmku2pvuj0003pdjq75t5g9e7" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -13744,6 +13744,12 @@ "additionalProperties": false } } + }, + "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": { @@ -14167,6 +14173,12 @@ "additionalProperties": false } } + }, + "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": { From 889a38508d598ff0139a3cb5fc5bca5465571c47 Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Tue, 27 Jan 2026 15:11:49 +0700 Subject: [PATCH 4/9] updates --- .../1.0.0/add-collection-bookmark.api.mdx | 10 +- .../1.0.0/add-collection.api.mdx | 10 +- .../1.0.0/add-note.api.mdx | 8 +- .../1.0.0/add-user-bookmark.api.mdx | 10 +- .../1.0.0/comments-controller-create.api.mdx | 2 +- .../1.0.0/comments-controller-get.api.mdx | 2 +- .../1.0.0/create-a-goal.api.mdx | 8 +- .../1.0.0/delete-a-goal.api.mdx | 4 +- .../1.0.0/delete-bookmark.api.mdx | 10 +- ...ete-collection-bookmark-by-details.api.mdx | 74 ++ .../delete-collection-bookmark-by-id.api.mdx | 10 +- .../1.0.0/delete-collection.api.mdx | 10 +- .../1.0.0/delete-note-by-id.api.mdx | 8 +- .../generate-timeline-estimation.api.mdx | 4 +- .../1.0.0/get-activity-days.api.mdx | 8 +- .../1.0.0/get-all-collection-items.api.mdx | 6 +- .../1.0.0/get-all-collections.api.mdx | 6 +- .../1.0.0/get-all-notes.api.mdx | 4 +- .../1.0.0/get-bookmark-collections.api.mdx | 6 +- .../1.0.0/get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../1.0.0/get-collection-items-by-id.api.mdx | 6 +- .../1.0.0/get-mutations.api.mdx | 10 +- .../1.0.0/get-notes-by-verse.api.mdx | 4 +- .../1.0.0/get-streaks.api.mdx | 6 +- .../1.0.0/get-todays-goal-plan.api.mdx | 6 +- .../1.0.0/get-user-bookmarks.api.mdx | 6 +- .../1.0.0/get-user-reading-sessions.api.mdx | 6 +- .../1.0.0/posts-controller-create.api.mdx | 4 +- .../1.0.0/posts-controller-edit.api.mdx | 4 +- .../1.0.0/posts-controller-feed.api.mdx | 2 +- .../1.0.0/posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../1.0.0/publish-note.api.mdx | 8 +- .../1.0.0/sidebar.js | 2 +- .../1.0.0/sync-local-mutations.api.mdx | 6 +- .../1.0.0/tags-controller-find.api.mdx | 2 +- .../1.0.0/update-a-goal.api.mdx | 6 +- .../1.0.0/update-collection.api.mdx | 8 +- .../1.0.0/update-note-by-id.api.mdx | 8 +- .../add-collection-bookmark.api.mdx | 10 +- .../add-collection.api.mdx | 10 +- .../add-note.api.mdx | 8 +- .../add-user-bookmark.api.mdx | 10 +- .../comments-controller-create.api.mdx | 2 +- .../comments-controller-get.api.mdx | 2 +- .../create-a-goal.api.mdx | 8 +- .../delete-a-goal.api.mdx | 4 +- .../delete-bookmark.api.mdx | 10 +- ...ete-collection-bookmark-by-details.api.mdx | 74 ++ .../delete-collection-bookmark-by-id.api.mdx | 10 +- .../delete-collection.api.mdx | 10 +- .../delete-note-by-id.api.mdx | 8 +- .../generate-timeline-estimation.api.mdx | 4 +- .../get-activity-days.api.mdx | 8 +- .../get-all-collection-items.api.mdx | 6 +- .../get-all-collections.api.mdx | 6 +- .../get-all-notes.api.mdx | 4 +- .../get-bookmark-collections.api.mdx | 6 +- .../get-bookmark.api.mdx | 4 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../get-collection-items-by-id.api.mdx | 6 +- .../get-mutations.api.mdx | 10 +- .../get-notes-by-verse.api.mdx | 4 +- .../get-streaks.api.mdx | 6 +- .../get-todays-goal-plan.api.mdx | 6 +- .../get-user-bookmarks.api.mdx | 6 +- .../get-user-reading-sessions.api.mdx | 6 +- .../posts-controller-create.api.mdx | 4 +- .../posts-controller-edit.api.mdx | 4 +- .../posts-controller-feed.api.mdx | 2 +- .../posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../publish-note.api.mdx | 8 +- docs/user_related_apis_versioned/sidebar.js | 2 +- .../sync-local-mutations.api.mdx | 6 +- .../tags-controller-find.api.mdx | 2 +- .../update-a-goal.api.mdx | 6 +- .../update-collection.api.mdx | 8 +- .../update-note-by-id.api.mdx | 8 +- openAPI/user-related-apis/v1.json | 1067 +++++++++++++++-- 89 files changed, 1421 insertions(+), 274 deletions(-) create mode 100644 docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx create mode 100644 docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx index 9d82db98..cc808eda 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmku2pw240008pdjqhq5r6or3"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkwbc0lu0008b0s0ax83876g"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
          Path Parameters
          Query Parameters
          Request Body
            anyOf
          +
          Path Parameters
          Query Parameters
          Request Body
            anyOf
          Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
          Schema
          +
          Schema
          + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
          Schema
            error object
          Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx index a2ea8421..d22507da 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
          data object
        +
      Schema
        data object
      The request is missing required parameters or is invalid. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
      Schema
      +
      Schema
      + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
      Schema
        error object
      Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx index 84f8d8c8..6e3a3da4 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-note.api.mdx @@ -5,7 +5,7 @@ description: "Add a new note." sidebar_label: "Add note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Add a new note.","parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"tags":["Notes"],"description":"Add a new note.","parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -62,7 +62,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
      Schema
      +
      Schema
      + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
      Schema
        error object
      Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx index b24fd21a..3559d11b 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx index 302d9b28..7d984271 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx index 5236685b..4848d9d7 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Parent comment not found diff --git a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx index 2d936714..535f27c1 100644 --- a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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:10","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}}}},"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":"cmkwbc0oi000fb0s04c737onv"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Create a goal -
    Query Parameters
    Header Parameters
    Request Body
      amount object required
      +
      Query Parameters
      Header Parameters
      Request Body
        amount object required
        The amount of the goal. Depending on the goal type, the amount value and format will be different @@ -38,11 +38,11 @@ The amount of the goal. Depending on the goal type, the amount value and format The amount of the goal. Depending on the goal type, the amount value and format will be different -
        = 1`"} 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."}}>
      +
      = 1`"} 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."}}>
    Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx index 23d9d26a..09b4768c 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
    Path Parameters
    Query Parameters
    Header Parameters
    +
    Path Parameters
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx index c361c96b..54871721 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmku2pvzi0006pdjq9cai8zg8"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkwbc0j40006b0s0gh8bh75y"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx new file mode 100644 index 00000000..491b1dc1 --- /dev/null +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx @@ -0,0 +1,74 @@ +--- +id: delete-collection-bookmark-by-details +title: "Delete collection bookmark by details" +description: "Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection." +sidebar_label: "Delete collection bookmark by details" +hide_title: true +hide_table_of_contents: true +api: {"description":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mo000bb0s0agvl9c6c"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}}},"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":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"},{"type":"object","required":["bookmarkId"],"additionalProperties":false,"title":"Bookmark ID"}],"title":"input"}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Delete collection bookmark by details","description":{"content":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"DELETE","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +sidebar_class_name: "delete api-method" +info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis +custom_edit_url: null +--- + +import ApiTabs from "@theme/ApiTabs"; +import MimeTabs from "@theme/MimeTabs"; +import ParamsItem from "@theme/ParamsItem"; +import ResponseSamples from "@theme/ResponseSamples"; +import SchemaItem from "@theme/SchemaItem"; +import SchemaTabs from "@theme/SchemaTabs"; +import DiscriminatorTabs from "@theme/DiscriminatorTabs"; +import TabItem from "@theme/TabItem"; + +## Delete collection bookmark by details + + + +Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. + +
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    + +Request has been handled successfully. + +
    Schema
    + +The request is missing required parameters or is invalid. + +
    Schema
    + +The request is unauthorized. + +
    Schema
    + +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. + +
    Schema
    + +Not Found. The resource being accessed does not exist. + +
    Schema
    + +Validation Error. The request includes one or more invalid params. Please check the request params and try again. + +
    Schema
    + +Too many requests, please try again later. + +
    Schema
    + +Server Error. Something went wrong, try again later. + +
    Schema
    + +Invalid response from the upstream server + +
    Schema
    + +The server is currently unable to handle the request due to a temporary overload or scheduled maintenance + +
    Schema
    + +The server did not receive a timely response from the upstream server. + +
    Schema
    + \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx index c084b291..c88b4843 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2i000apdjqae7igz3n"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmku2pw2i000bpdjqeuau0kl3"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mu000cb0s0cm6n09p7"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkwbc0mu000db0s005p84503"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx index 97f9b35f..acb2544f 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2b0009pdjq26tddi7u"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0m10009b0s0d05fapzk"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx index 41443ed5..9e2c7e4e 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a note by its ID." sidebar_label: "Delete note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/generate-timeline-estimation.api.mdx b/docs/user_related_apis_versioned/1.0.0/generate-timeline-estimation.api.mdx index cab6d179..c51df553 100644 --- a/docs/user_related_apis_versioned/1.0.0/generate-timeline-estimation.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/generate-timeline-estimation.api.mdx @@ -5,7 +5,7 @@ description: "Generate a timeline up to a week of the minimum daily amount requi sidebar_label: "Generate timeline estimation" hide_title: true hide_table_of_contents: true -api: {"description":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"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:10","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":{"type":"object","properties":{"week":{"type":"array","items":{"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:10"},{"type":"integer","minimum":1,"example":600}],"description":"The amount of the day's goal."}},"required":["date","amount"],"additionalProperties":false,"title":"EstimatedGoalTimelineDay"}}},"additionalProperties":false,"title":"EstimatedGoalTimeline"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/estimate","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Generate timeline estimation","description":{"content":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","type":"text/plain"},"url":{"path":["v1","goals","estimate"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) The amount of the goal. Depending on the goal type, the amount value and format will be different","type":"text/plain"},"key":"amount","value":""},{"disabled":false,"description":{"content":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based.","type":"text/plain"},"key":"duration","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","tags":["Goals"],"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:10","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":{"type":"object","properties":{"week":{"type":"array","items":{"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:10"},{"type":"integer","minimum":1,"example":600}],"description":"The amount of the day's goal."}},"required":["date","amount"],"additionalProperties":false,"title":"EstimatedGoalTimelineDay"}}},"additionalProperties":false,"title":"EstimatedGoalTimeline"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/estimate","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Generate timeline estimation","description":{"content":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","type":"text/plain"},"url":{"path":["v1","goals","estimate"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) The amount of the goal. Depending on the goal type, the amount value and format will be different","type":"text/plain"},"key":"amount","value":""},{"disabled":false,"description":{"content":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based.","type":"text/plain"},"key":"duration","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Generate a timeline up to a week of the minimum daily amount required to meet the goal. -
    Query Parameters
    Header Parameters
    +
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx index 2a8e8466..192454a5 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
      • ranges object
      +
      Schema
        data object[]
      • Array [
        • ranges object
        The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
      • ]
        • pagination object
      +
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx index a53da869..76fffe0f 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx index 59aa9185..9c3ac0f3 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx index 92c35447..8396e663 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx index 081f484d..4d0e7d3a 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx index bbb23724..2844c2e2 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx index dcd4626b..56d92496 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx index 3fb785d6..3f9ca8e5 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmku2pw36000cpdjqfahw9b56"}},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkwbc0ng000eb0s04gn2b009"}},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx index 4c2844f4..4cfd066a 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-mutations.api.mdx @@ -5,7 +5,7 @@ description: "Get list of mutations that were applied to resources after a certa sidebar_label: "Get mutations" hide_title: true hide_table_of_contents: true -api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":false}}},"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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }.","example":true,"default":false},"required":false,"description":"When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Get list of mutations that were applied to resources after a certain point in time. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. @@ -62,7 +62,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx index 51110092..fc1194df 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx index f3720bb6..c6b28611 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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 streak.","example":"cmku2pwch000fpdjqbtmhe78f"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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 streak.","example":"cmkwbc0zd000hb0s04j4j2nuj"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx index 7b7f6200..95435625 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"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":"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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get today's goal plan. -
    Query Parameters
    Header Parameters
    +
    Query Parameters
    Header Parameters
    Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx index 7aee1569..4d70127e 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx index 088abc50..c972d36f 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pwby000epdjqg6eqec02"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0yr000gb0s01wvy1ntj"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx index 7e93d7d8..7b9f0d87 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:33.823Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:28.056Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx index 1c2a909f..0f339c94 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:33.823Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:28.056Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx index d4bdb4a9..492314f2 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx index 2d61a02e..e0525ce6 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx index d587149d..563707c4 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx index 5bc2a5b7..56cdd332 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx index 77bcd283..77c56933 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx index c41dd13e..4fbf84d8 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx index f0d0e5eb..76e63a6d 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx b/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx index 16af75da..697c69bf 100644 --- a/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/publish-note.api.mdx @@ -5,7 +5,7 @@ description: "Publish a note to QR." sidebar_label: "Publish note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -54,7 +54,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/sidebar.js b/docs/user_related_apis_versioned/1.0.0/sidebar.js index 38807e5d..29b33c18 100644 --- a/docs/user_related_apis_versioned/1.0.0/sidebar.js +++ b/docs/user_related_apis_versioned/1.0.0/sidebar.js @@ -1 +1 @@ -module.exports = [{"type":"doc","id":"user_related_apis_versioned/1.0.0/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-delete-account","label":"Delete user account permanently","className":"api-method delete"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Sync","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-mutations","label":"Get mutations","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/sync-local-mutations","label":"Sync local mutations","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file +module.exports = [{"type":"doc","id":"user_related_apis_versioned/1.0.0/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details","label":"Delete collection bookmark by details","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/users-controller-delete-account","label":"Delete user account permanently","className":"api-method delete"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Sync","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/get-mutations","label":"Get mutations","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/sync-local-mutations","label":"Sync local mutations","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/1.0.0/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx index 066811e2..a8027430 100644 --- a/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/sync-local-mutations.api.mdx @@ -5,7 +5,7 @@ description: "An endpoint to sync local mutations to the server." sidebar_label: "Sync local mutations" hide_title: true hide_table_of_contents: true -api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -68,9 +68,9 @@ Not Found. The resource being accessed does not exist.
    Schema
    -Out of Sync Error. The client lastMutationAt does not match server state. +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. -
    Schema
      error object
    +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. diff --git a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx index 5768e9ec..7fb62434 100644 --- a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
    Schema
    • Array [
    • ]
    +
    Schema
    • Array [
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx index 1125b0d5..a5cc30ed 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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:10","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}}}},"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}}}},"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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
    Path Parameters
    Query Parameters
    Header Parameters
    Request Body
      amount object
      +
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        The amount of the goal. Depending on the goal type, the amount value and format will be different @@ -38,7 +38,7 @@ The amount of the goal. Depending on the goal type, the amount value and format The amount of the goal. Depending on the goal type, the amount value and format will be different -
        = 1`"} 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."}}>
      +
      = 1`"} 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."}}>
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx index 1c121996..56e9d8d0 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-collection.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing collection." sidebar_label: "Update collection" hide_title: true hide_table_of_contents: true -api: {"description":"Update an existing collection.","tags":["Collections"],"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."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the collection to be updated."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update an existing collection.","tags":["Collections"],"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."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the collection to be updated."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx index c39cec5b..5de84078 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Update a note by its ID." sidebar_label: "Update note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -58,7 +58,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx index e98387fc..0350433d 100644 --- a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmku2pw240008pdjqhq5r6or3"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkwbc0lu0008b0s0ax83876g"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    +
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/add-collection.api.mdx b/docs/user_related_apis_versioned/add-collection.api.mdx index f54ffcd4..2b1ae662 100644 --- a/docs/user_related_apis_versioned/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/add-note.api.mdx b/docs/user_related_apis_versioned/add-note.api.mdx index db45f525..68f8a1ad 100644 --- a/docs/user_related_apis_versioned/add-note.api.mdx +++ b/docs/user_related_apis_versioned/add-note.api.mdx @@ -5,7 +5,7 @@ description: "Add a new note." sidebar_label: "Add note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Add a new note.","parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"tags":["Notes"],"description":"Add a new note.","parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the note should be saved to the QuranReflect.","example":true},"attachedEntity":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["body","saveToQR"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":true,"attachedEntity":{"entityId":"entity123","entityType":"reflection","entityMetadata":{"key":"value"}},"ranges":["2:255-2:257"]},"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 ## 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"},"postman":{"name":"Add note","description":{"content":"Add a new note.","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -62,7 +62,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx index 9d3abf5f..d6adce6d 100644 --- a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/comments-controller-create.api.mdx index ef7620cc..885275ce 100644 --- a/docs/user_related_apis_versioned/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/comments-controller-get.api.mdx index f254407e..b6cda2b6 100644 --- a/docs/user_related_apis_versioned/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Parent comment not found diff --git a/docs/user_related_apis_versioned/create-a-goal.api.mdx b/docs/user_related_apis_versioned/create-a-goal.api.mdx index 58d2f01f..366a3184 100644 --- a/docs/user_related_apis_versioned/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"required":["type","amount","category"],"additionalProperties":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":{"id":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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:10","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}}}},"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":"cmkwbc0oi000fb0s04c737onv"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Create a goal -
    Query Parameters
    Header Parameters
    Request Body
      amount object required
      +
      Query Parameters
      Header Parameters
      Request Body
        amount object required
        The amount of the goal. Depending on the goal type, the amount value and format will be different @@ -38,11 +38,11 @@ The amount of the goal. Depending on the goal type, the amount value and format The amount of the goal. Depending on the goal type, the amount value and format will be different -
        = 1`"} 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."}}>
      +
      = 1`"} 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."}}>
    Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/delete-a-goal.api.mdx index c0ec306b..116f4082 100644 --- a/docs/user_related_apis_versioned/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"required":true,"description":"The id of the goal."},{"in":"query","name":"category","schema":{"type":"string","enum":["QURAN","COURSE","QURAN_READING_PROGRAM"],"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
    Path Parameters
    Query Parameters
    Header Parameters
    +
    Path Parameters
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/delete-bookmark.api.mdx index 39ce7e5f..82af9b64 100644 --- a/docs/user_related_apis_versioned/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmku2pvzi0006pdjq9cai8zg8"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkwbc0j40006b0s0gh8bh75y"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx b/docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx new file mode 100644 index 00000000..eb2ca6d2 --- /dev/null +++ b/docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx @@ -0,0 +1,74 @@ +--- +id: delete-collection-bookmark-by-details +title: "Delete collection bookmark by details" +description: "Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection." +sidebar_label: "Delete collection bookmark by details" +hide_title: true +hide_table_of_contents: true +api: {"description":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mo000bb0s0agvl9c6c"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}}},"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":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"},{"type":"object","required":["bookmarkId"],"additionalProperties":false,"title":"Bookmark ID"}],"title":"input"}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Delete collection bookmark by details","description":{"content":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"DELETE","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +sidebar_class_name: "delete api-method" +info_path: docs/user_related_apis_versioned/user-related-apis +custom_edit_url: null +--- + +import ApiTabs from "@theme/ApiTabs"; +import MimeTabs from "@theme/MimeTabs"; +import ParamsItem from "@theme/ParamsItem"; +import ResponseSamples from "@theme/ResponseSamples"; +import SchemaItem from "@theme/SchemaItem"; +import SchemaTabs from "@theme/SchemaTabs"; +import DiscriminatorTabs from "@theme/DiscriminatorTabs"; +import TabItem from "@theme/TabItem"; + +## Delete collection bookmark by details + + + +Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. + +
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    + +Request has been handled successfully. + +
    Schema
    + +The request is missing required parameters or is invalid. + +
    Schema
    + +The request is unauthorized. + +
    Schema
    + +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. + +
    Schema
    + +Not Found. The resource being accessed does not exist. + +
    Schema
    + +Validation Error. The request includes one or more invalid params. Please check the request params and try again. + +
    Schema
    + +Too many requests, please try again later. + +
    Schema
    + +Server Error. Something went wrong, try again later. + +
    Schema
    + +Invalid response from the upstream server + +
    Schema
    + +The server is currently unable to handle the request due to a temporary overload or scheduled maintenance + +
    Schema
    + +The server did not receive a timely response from the upstream server. + +
    Schema
    + \ No newline at end of file diff --git a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx index 4974a094..3be0daeb 100644 --- a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2i000apdjqae7igz3n"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmku2pw2i000bpdjqeuau0kl3"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mu000cb0s0cm6n09p7"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkwbc0mu000db0s005p84503"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/delete-collection.api.mdx b/docs/user_related_apis_versioned/delete-collection.api.mdx index 4ee0b19f..7e95d9a0 100644 --- a/docs/user_related_apis_versioned/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmku2pw2b0009pdjq26tddi7u"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0m10009b0s0d05fapzk"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/delete-note-by-id.api.mdx b/docs/user_related_apis_versioned/delete-note-by-id.api.mdx index ee0b0a28..300c728e 100644 --- a/docs/user_related_apis_versioned/delete-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/delete-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a note by its ID." sidebar_label: "Delete note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Delete a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The ID of the note to delete."},"required":true,"description":"The ID of the note to delete."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"success":{"type":"boolean"}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/generate-timeline-estimation.api.mdx b/docs/user_related_apis_versioned/generate-timeline-estimation.api.mdx index 63948ca2..afab69ad 100644 --- a/docs/user_related_apis_versioned/generate-timeline-estimation.api.mdx +++ b/docs/user_related_apis_versioned/generate-timeline-estimation.api.mdx @@ -5,7 +5,7 @@ description: "Generate a timeline up to a week of the minimum daily amount requi sidebar_label: "Generate timeline estimation" hide_title: true hide_table_of_contents: true -api: {"description":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"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:10","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":{"type":"object","properties":{"week":{"type":"array","items":{"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:10"},{"type":"integer","minimum":1,"example":600}],"description":"The amount of the day's goal."}},"required":["date","amount"],"additionalProperties":false,"title":"EstimatedGoalTimelineDay"}}},"additionalProperties":false,"title":"EstimatedGoalTimeline"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/estimate","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Generate timeline estimation","description":{"content":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","type":"text/plain"},"url":{"path":["v1","goals","estimate"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) The amount of the goal. Depending on the goal type, the amount value and format will be different","type":"text/plain"},"key":"amount","value":""},{"disabled":false,"description":{"content":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based.","type":"text/plain"},"key":"duration","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","tags":["Goals"],"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:10","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":{"type":"object","properties":{"week":{"type":"array","items":{"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:10"},{"type":"integer","minimum":1,"example":600}],"description":"The amount of the day's goal."}},"required":["date","amount"],"additionalProperties":false,"title":"EstimatedGoalTimelineDay"}}},"additionalProperties":false,"title":"EstimatedGoalTimeline"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/estimate","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Generate timeline estimation","description":{"content":"Generate a timeline up to a week of the minimum daily amount required to meet the goal.","type":"text/plain"},"url":{"path":["v1","goals","estimate"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) The amount of the goal. Depending on the goal type, the amount value and format will be different","type":"text/plain"},"key":"amount","value":""},{"disabled":false,"description":{"content":"The duration of the goal in days. If it's empty it means the goal is a daily goal and not duration-based.","type":"text/plain"},"key":"duration","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Generate a timeline up to a week of the minimum daily amount required to meet the goal. -
    Query Parameters
    Header Parameters
    +
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/get-activity-days.api.mdx b/docs/user_related_apis_versioned/get-activity-days.api.mdx index 2c2e36d0..9cd112d6 100644 --- a/docs/user_related_apis_versioned/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
      • ranges object
      +
      Schema
        data object[]
      • Array [
        • ranges object
        The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
      • ]
        • pagination object
      +
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx index af642eab..80738542 100644 --- a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collections.api.mdx b/docs/user_related_apis_versioned/get-all-collections.api.mdx index f23eab13..93cc120e 100644 --- a/docs/user_related_apis_versioned/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-notes.api.mdx b/docs/user_related_apis_versioned/get-all-notes.api.mdx index a94daeb9..6ce79e3e 100644 --- a/docs/user_related_apis_versioned/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx index 2b373111..18a3721f 100644 --- a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark.api.mdx b/docs/user_related_apis_versioned/get-bookmark.api.mdx index 646e6d6a..049edc2e 100644 --- a/docs/user_related_apis_versioned/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get a bookmark by details Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx index ca6c6ff9..bd9ef8e5 100644 --- a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx index 735ef281..7d07be1c 100644 --- a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmku2pw36000cpdjqfahw9b56"}},{"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pw0h0007pdjqc10s2chz"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkwbc0ng000eb0s04gn2b009"}},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-mutations.api.mdx b/docs/user_related_apis_versioned/get-mutations.api.mdx index 92ca3797..bd11cd0a 100644 --- a/docs/user_related_apis_versioned/get-mutations.api.mdx +++ b/docs/user_related_apis_versioned/get-mutations.api.mdx @@ -5,7 +5,7 @@ description: "Get list of mutations that were applied to resources after a certa sidebar_label: "Get mutations" hide_title: true hide_table_of_contents: true -api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, only returns lastMutationAt without mutations.","example":true,"default":false},"required":false,"description":"When true, only returns lastMutationAt without mutations."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":false}}},"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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, only returns lastMutationAt without mutations.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get list of mutations that were applied to resources after a certain point in time.","tags":["Sync"],"parameters":[{"in":"query","name":"mutationsSince","schema":{"type":"number","format":"float","description":"The timestamp to get mutations since.","example":1731636500303},"required":true,"description":"The timestamp to get mutations since."},{"in":"query","name":"resources","schema":{"type":"string","description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","example":"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK"},"required":false,"description":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned."},{"in":"query","name":"metadataOnly","schema":{"type":"boolean","description":"When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }.","example":true,"default":false},"required":false,"description":"When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":1000,"description":"Maximum number of mutations to return per page (1-1000).","example":100,"default":100},"required":false,"description":"Maximum number of mutations to return per page (1-1000)."},{"in":"query","name":"page","schema":{"type":"number","format":"float","minimum":1,"description":"Page number (1-based).","example":1,"default":1},"required":false,"description":"Page number (1-based)."}],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that occurred after lastMutationAt. Will be omitted when metadataOnly is set to true.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation. This should be used for subsequent sync requests. If metadataOnly is true, this will be the only field returned.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for get mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"get","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get mutations","description":{"content":"Get list of mutations that were applied to resources after a certain point in time.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp to get mutations since.","type":"text/plain"},"key":"mutationsSince","value":""},{"disabled":false,"description":{"content":"Comma-separated list of resources to filter mutations by (e.g. \"BOOKMARK,COLLECTION,COLLECTION_BOOKMARK,NOTE\"). If not provided, all accessible resources will be returned.","type":"text/plain"},"key":"resources","value":""},{"disabled":false,"description":{"content":"When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }.","type":"text/plain"},"key":"metadataOnly","value":""},{"disabled":false,"description":{"content":"Maximum number of mutations to return per page (1-1000).","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Page number (1-based).","type":"text/plain"},"key":"page","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Get list of mutations that were applied to resources after a certain point in time. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. @@ -62,7 +62,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx index ecef1d02..cc11005c 100644 --- a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-streaks.api.mdx b/docs/user_related_apis_versioned/get-streaks.api.mdx index 39c7e72e..8a773140 100644 --- a/docs/user_related_apis_versioned/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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 streak.","example":"cmku2pwch000fpdjqbtmhe78f"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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 streak.","example":"cmkwbc0zd000hb0s04j4j2nuj"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx index d12a3673..c3099cc0 100644 --- a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["QURAN_TIME","QURAN_PAGES","QURAN_RANGE","COURSE","QURAN_READING_PROGRAM"],"description":"The type of the goal.","example":"QURAN_TIME"},"required":true,"description":"The type 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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmku2pvv00004pdjqb000bm4m"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"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":"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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get today's goal plan. -
    Query Parameters
    Header Parameters
    +
    Query Parameters
    Header Parameters
    Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx index 7c608981..608899ee 100644 --- a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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":"object","properties":{"id":{"type":"string","example":"cmku2pvz90005pdjq1l2ndb81"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx index 44b7ec8a..b5a8d1c3 100644 --- a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmku2pvui0000pdjqec4ug7py"},"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":"cmku2pvuj0001pdjqgbvqbbqw"},"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","example":"cmku2pwby000epdjqg6eqec02"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmku2pvuj0002pdjqei7wcrwp"},"endCursor":{"type":"string","example":"cmku2pvuj0003pdjq75t5g9e7"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0yr000gb0s01wvy1ntj"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/posts-controller-create.api.mdx index 8a2259c0..2cabd1c9 100644 --- a/docs/user_related_apis_versioned/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:30.634Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:24.493Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx index a6bae1f7..c1a98753 100644 --- a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-25T18:33:30.634Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:24.493Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx index 2c4cc68c..526f6110 100644 --- a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx index 54141cac..0d9c9d2e 100644 --- a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx index a052a793..18d8d089 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx index a6e535e8..7822fc33 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx index 80948c4e..64033c4d 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx index b669c73e..11611200 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx index 1e29eca2..d73df9ab 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/publish-note.api.mdx b/docs/user_related_apis_versioned/publish-note.api.mdx index 47447d78..aeedcfff 100644 --- a/docs/user_related_apis_versioned/publish-note.api.mdx +++ b/docs/user_related_apis_versioned/publish-note.api.mdx @@ -5,7 +5,7 @@ description: "Publish a note to QR." sidebar_label: "Publish note" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Publish a note to QR.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:112-2:115"]}},"required":["body"],"additionalProperties":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":{"success":{"type":"boolean"},"postId":{"type":"number","format":"float"}},"required":["success"],"additionalProperties":false,"description":"Response object indicating the success of the note publishing operation and the optional post ID if successful.","example":{"success":true,"postId":123}}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/notes/:noteId/publish","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","ranges":["2:112-2:115"]},"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 ## 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"}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -54,7 +54,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/sidebar.js b/docs/user_related_apis_versioned/sidebar.js index 2be89f73..2dc02b0b 100644 --- a/docs/user_related_apis_versioned/sidebar.js +++ b/docs/user_related_apis_versioned/sidebar.js @@ -1 +1 @@ -module.exports = [{"type":"doc","id":"user_related_apis_versioned/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-delete-account","label":"Delete user account permanently","className":"api-method delete"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Sync","items":[{"type":"doc","id":"user_related_apis_versioned/get-mutations","label":"Get mutations","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/sync-local-mutations","label":"Sync local mutations","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file +module.exports = [{"type":"doc","id":"user_related_apis_versioned/user-related-apis"},{"type":"category","label":"Collections","items":[{"type":"doc","id":"user_related_apis_versioned/add-collection","label":"Add collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-all-collections","label":"Get all collections","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-collection-bookmark","label":"Add collection Bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection-bookmark-by-details","label":"Delete collection bookmark by details","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/delete-collection","label":"Delete collection","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-collection-items-by-id","label":"Get collection items by id","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-collection","label":"Update collection","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/delete-collection-bookmark-by-id","label":"Delete collection bookmark by id","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-all-collection-items","label":"Get all collection items","className":"api-method get"}]},{"type":"category","label":"Bookmarks","items":[{"type":"doc","id":"user_related_apis_versioned/add-user-bookmark","label":"Add user bookmark","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-bookmarks","label":"Get user bookmarks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/delete-bookmark","label":"Delete Bookmark","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs","label":"Get bookmarks within a range of Ayahs","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark","label":"Get bookmark","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-bookmark-collections","label":"Get bookmark collections","className":"api-method get"}]},{"type":"category","label":"Preferences","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-preference","label":"Add or update preference","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-preferences","label":"Get user preferences","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/bulk-add-or-update-preferences","label":"Bulk add or update preferences","className":"api-method post"}]},{"type":"category","label":"Reading Sessions","items":[{"type":"doc","id":"user_related_apis_versioned/add-or-update-user-reading-session","label":"Add or update user reading session","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-user-reading-sessions","label":"Get user reading sessions","className":"api-method get"}]},{"type":"category","label":"Goals","items":[{"type":"doc","id":"user_related_apis_versioned/get-todays-goal-plan","label":"Get today's goal plan","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-a-goal","label":"Update a goal","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/delete-a-goal","label":"Delete a goal","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/create-a-goal","label":"Create a goal","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/generate-timeline-estimation","label":"Generate timeline estimation","className":"api-method get"}]},{"type":"category","label":"Streaks","items":[{"type":"doc","id":"user_related_apis_versioned/get-streaks","label":"Get streaks","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-current-streak-days","label":"Get current streak days","className":"api-method get"}]},{"type":"category","label":"Activity Days","items":[{"type":"doc","id":"user_related_apis_versioned/add-update-activity-day","label":"Add/update activity day","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-activity-days","label":"Get activity days","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/estimate-reading-time","label":"Estimate reading time","className":"api-method get"}]},{"type":"category","label":"Users","items":[{"type":"doc","id":"user_related_apis_versioned/users-controller-edit-profile","label":"Edit user profile","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/users-controller-profile","label":"Get user profile","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-update-profile","label":"Update user profile","className":"api-method put"},{"type":"doc","id":"user_related_apis_versioned/users-controller-rooms","label":"Get logged-in user rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-search","label":"Search for users","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-toggle-follow","label":"Toggle follow/unfollow a user","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-remove-follower","label":"Remove a follower","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-profile","label":"Get user profile by id or username","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-followers","label":"Get user followers","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-get-user-following","label":"Get users followed by user","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/users-controller-delete-account","label":"Delete user account permanently","className":"api-method delete"}]},{"type":"category","label":"Notes","items":[{"type":"doc","id":"user_related_apis_versioned/get-all-notes","label":"Get all notes","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/add-note","label":"Add note","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse","label":"Get notes by verse","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-attached-entity","label":"Get notes by attached entity","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-count-within-verse-range","label":"Get notes count within verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-notes-by-verse-range","label":"Get notes by verse range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/get-note-by-id","label":"Get note by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/update-note-by-id","label":"Update note by ID","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/delete-note-by-id","label":"Delete note by ID","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/publish-note","label":"Publish note","className":"api-method post"}]},{"type":"category","label":"Sync","items":[{"type":"doc","id":"user_related_apis_versioned/get-mutations","label":"Get mutations","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/sync-local-mutations","label":"Sync local mutations","className":"api-method post"}]},{"type":"category","label":"Rooms","items":[{"type":"doc","id":"user_related_apis_versioned/rooms-controller-admins-access","label":"Update room admin access","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-group","label":"Update a group","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-group","label":"Create a new group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-page","label":"Update a page","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-create-new-page","label":"Create a new page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-members","label":"Get room members","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-invite-user-to-room","label":"Invite user to room","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-invite","label":"Accept room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-reject-invite","label":"Reject room invite","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-remove-member","label":"Remove member from room","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-rooms","label":"Get joined or managed rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-search-rooms","label":"Search rooms","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile","label":"Get room profile by URL or subdomain","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-accept-by-private-token","label":"Accept room invite by private token","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-profile-by-id","label":"Get room profile by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-get-room-posts","label":"Get room posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-join-room","label":"Join a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-leave-group","label":"Leave a group","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-follow-page","label":"Follow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-unfollow-page","label":"Unfollow a page","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/rooms-controller-update-post-privacy","label":"Update post privacy in room","className":"api-method patch"}]},{"type":"category","label":"Posts","items":[{"type":"doc","id":"user_related_apis_versioned/posts-controller-feed","label":"Get posts feed","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-loggedin-user-posts","label":"Get current user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-find-one","label":"Get post by ID","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-delete","label":"Delete post","className":"api-method delete"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-edit","label":"Edit post","className":"api-method patch"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-view-tracking","label":"Track post view","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-create","label":"Create post","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-report-abuse","label":"Report post abuse","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-user-post","label":"Get user posts","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-like","label":"Toggle post like","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-toggle-save","label":"Toggle post save","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-comments","label":"Get post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-all-comment","label":"Get all post comments","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-export-multiple-posts","label":"Export posts as PDF","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-count-within-range","label":"Get posts count within range","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/posts-controller-get-my-posts-by-verse","label":"Get posts by verse","className":"api-method get"}]},{"type":"category","label":"Tags","items":[{"type":"doc","id":"user_related_apis_versioned/tags-controller-find","label":"Search and retrieve tags","className":"api-method get"}]},{"type":"category","label":"Comments","items":[{"type":"doc","id":"user_related_apis_versioned/comments-controller-create","label":"Create a new comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-delete-comment","label":"Delete a comment","className":"api-method get"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-toggle-like","label":"Toggle like/unlike a comment","className":"api-method post"},{"type":"doc","id":"user_related_apis_versioned/comments-controller-get","label":"Get replies to a comment","className":"api-method get"}]}]; \ No newline at end of file diff --git a/docs/user_related_apis_versioned/sync-local-mutations.api.mdx b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx index 31d0d487..d9da4517 100644 --- a/docs/user_related_apis_versioned/sync-local-mutations.api.mdx +++ b/docs/user_related_apis_versioned/sync-local-mutations.api.mdx @@ -5,7 +5,7 @@ description: "An endpoint to sync local mutations to the server." sidebar_label: "Sync local mutations" hide_title: true hide_table_of_contents: true -api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"An endpoint to sync local mutations to the server.","tags":["Sync"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"Resource the mutation applies to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"Server's ID for finding the resource during update/delete operations.","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"Resource data. Format depends on resource type.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}},"required":["type","resource"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"}}},"required":["mutations"],"additionalProperties":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":{"mutations":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["CREATE","UPDATE","DELETE"],"description":"The type of the mutation","example":"CREATE"},"resource":{"type":"string","enum":["BOOKMARK","COLLECTION","COLLECTION_BOOKMARK","NOTE"],"description":"The resource the mutation was applied to.","example":"BOOKMARK"},"resourceId":{"type":"string","description":"The id of the resource the mutation was applied to. Will not be present for resources that use composite keys (e.g. COLLECTION_BOOKMARK uses data.collection and data.bookmark instead).","example":"lqc794i0qnxq4pdlfanfbd2r"},"data":{"type":"object","properties":{},"description":"The latest version of the data of the resource that was mutated. Will be empty when the mutation is a delete.","example":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}},"timestamp":{"type":"number","format":"float","description":"Unix timestamp when the latest mutation of the resource occurred","example":1731636500303}},"required":["type","resource","timestamp"],"additionalProperties":false,"description":"Represents a single mutation/change to a resource"},"description":"Array of mutations that were successfully applied on the server.","example":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"u54maufl0ftmarp73ei0hg64","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3},"timestamp":1769340915572},{"type":"UPDATE","resource":"COLLECTION","resourceId":"na6orcv0pbcomiphmkv0yhma","data":{"name":"New collection!","slug":"new-collection","isPrivate":true},"timestamp":1769340915572},{"type":"CREATE","resource":"COLLECTION_BOOKMARK","data":{"collection":"na6orcv0pbcomiphmkv0yhma","bookmark":"u54maufl0ftmarp73ei0hg64"},"timestamp":1769340915575},{"type":"DELETE","resource":"NOTE","resourceId":"his2lubkxxr3l102nqptmnur","data":{},"timestamp":1769341113173}]},"page":{"type":"number","format":"float","description":"Current page number","example":1},"limit":{"type":"number","format":"float","description":"Items per page","example":100},"total":{"type":"number","format":"float","description":"Total number of mutations","example":150},"hasMore":{"type":"boolean","description":"Whether more pages exist","example":true},"lastMutationAt":{"type":"number","format":"float","description":"Timestamp of the latest mutation that was applied on the server. This should be used for subsequent sync requests.","example":1731636500303}},"required":["lastMutationAt"],"additionalProperties":false,"description":"Response schema for post mutations endpoint"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"422":{"description":"Validation Error. The request includes one or more invalid params.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"ValidationError"},"message":{"type":"string","example":"Invalid mutations"}}}}},"examples":{"Invalid mutations format":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutations"}}},"Too many mutations":{"value":{"success":false,"error":{"code":"ValidationError","message":"Mutations must not exceed 100"}}},"Missing resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resource at mutation[0]"}}},"Invalid resource":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resource: \"invalidResource\" at mutation[0]"}}},"Missing mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing mutation type at mutation[0]"}}},"Invalid mutation type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid mutation type: \"invalidType\" at mutation[0]"}}},"Missing resourceId":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing resourceId at mutation[0]"}}},"Invalid resourceId type":{"value":{"success":false,"error":{"code":"ValidationError","message":"Invalid resourceId at mutation[0]"}}},"Missing data":{"value":{"success":false,"error":{"code":"ValidationError","message":"Missing data at mutation[0]"}}}}}}},"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}}}}},"method":"post","path":"/v1/sync","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"mutations":[{"type":"CREATE","resource":"BOOKMARK","resourceId":"lqc794i0qnxq4pdlfanfbd2r","data":{"bookmarkType":"ayah","bookmarkGroup":"verses_6236","key":6,"verseNumber":3}}]},"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 ## 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"},"postman":{"name":"Sync local mutations","description":{"content":"An endpoint to sync local mutations to the server.","type":"text/plain"},"url":{"path":["v1","sync"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. The value needs to match the latest value from get mutations endpoint, otherwise, the request will be rejected.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -68,9 +68,9 @@ Not Found. The resource being accessed does not exist.
    Schema
    -Out of Sync Error. The client lastMutationAt does not match server state. +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. -
    Schema
      error object
    +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. diff --git a/docs/user_related_apis_versioned/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/tags-controller-find.api.mdx index 1f4e47fa..b38c2759 100644 --- a/docs/user_related_apis_versioned/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
    Schema
    • Array [
    • ]
    +
    Schema
    • Array [
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/update-a-goal.api.mdx b/docs/user_related_apis_versioned/update-a-goal.api.mdx index 3568322e..09ef7bfa 100644 --- a/docs/user_related_apis_versioned/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmku2pw4c000dpdjq8fb6hiz4"},"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"],"description":"The type of the goal.","example":"QURAN_TIME"},"amount":{"oneOf":[{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$","example":"1:5-1:10","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"],"description":"The category of the goal"}},"additionalProperties":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":{},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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:10","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}}}},"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}}}},"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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
    Path Parameters
    Query Parameters
    Header Parameters
    Request Body
      amount object
      +
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        The amount of the goal. Depending on the goal type, the amount value and format will be different @@ -38,7 +38,7 @@ The amount of the goal. Depending on the goal type, the amount value and format The amount of the goal. Depending on the goal type, the amount value and format will be different -
        = 1`"} 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."}}>
      +
      = 1`"} 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."}}>
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/update-collection.api.mdx b/docs/user_related_apis_versioned/update-collection.api.mdx index 95eaa6b4..eef4d35b 100644 --- a/docs/user_related_apis_versioned/update-collection.api.mdx +++ b/docs/user_related_apis_versioned/update-collection.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing collection." sidebar_label: "Update collection" hide_title: true hide_table_of_contents: true -api: {"description":"Update an existing collection.","tags":["Collections"],"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."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the collection to be updated."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update an existing collection.","tags":["Collections"],"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."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"The new name of the collection to be updated."}},"required":["name"],"additionalProperties":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":["collection renamed"]}},"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"string"},"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 ## 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"},"postman":{"name":"Update collection","description":{"content":"Update an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be updated.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -50,7 +50,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/docs/user_related_apis_versioned/update-note-by-id.api.mdx b/docs/user_related_apis_versioned/update-note-by-id.api.mdx index 10bcfb2e..f64942d8 100644 --- a/docs/user_related_apis_versioned/update-note-by-id.api.mdx +++ b/docs/user_related_apis_versioned/update-note-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Update a note by its ID." sidebar_label: "Update note by ID" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Update a note by its ID.","parameters":[{"in":"path","name":"noteId","schema":{"type":"string","description":"The unique identifier of the note to be retrieved or manipulated.","example":"asda12312312"},"required":true,"description":"The unique identifier of the note to be retrieved or manipulated."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"saveToQR":{"type":"boolean","description":"Indicates whether the updated note should be saved to the QuranReflect, defaults to false.","example":false,"default":false}},"required":["body"],"additionalProperties":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":{"id":{"type":"string","description":"The unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"patch","path":"/v1/notes/:noteId","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"body":"This is a sample note body.","saveToQR":false},"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 ## 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"}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -58,7 +58,11 @@ Forbidden error. Can either be due to access token not being passed, having been Not Found. The resource being accessed does not exist. -
    Schema
    +
    Schema
    + +Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation. + +
    Schema
      error object
    Validation Error. The request includes one or more invalid params. Please check the request params and try again. diff --git a/openAPI/user-related-apis/v1.json b/openAPI/user-related-apis/v1.json index 7cd9ea47..3b05833c 100644 --- a/openAPI/user-related-apis/v1.json +++ b/openAPI/user-related-apis/v1.json @@ -34,7 +34,7 @@ "Bookmark": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmku2pvz90005pdjq1l2ndb81" }, + "id": { "type": "string", "example": "cmkwbc0iu0005b0s028eh6ztm" }, "createdAt": { "type": "string", "format": "date-time", @@ -51,7 +51,7 @@ "Collection": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmku2pw0h0007pdjqc10s2chz" }, + "id": { "type": "string", "example": "cmkwbc0k10007b0s0g5jh3l4e" }, "updatedAt": { "type": "string", "format": "date-time", @@ -357,7 +357,7 @@ "ReadingSession": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmku2pwby000epdjqg6eqec02" }, + "id": { "type": "string", "example": "cmkwbc0yr000gb0s01wvy1ntj" }, "updatedAt": { "type": "string", "format": "date-time", @@ -1260,6 +1260,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -1447,7 +1493,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -1458,7 +1504,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -1481,11 +1527,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -1718,7 +1764,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be added.", - "example": "cmku2pw240008pdjqhq5r6or3" + "example": "cmkwbc0lu0008b0s0ax83876g" }, "required": true, "description": "The Id of the collection to be added." @@ -1900,6 +1946,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -2000,29 +2092,352 @@ "type": "string", "example": "service_unavailable" }, - "success": { "type": "boolean", "example": false } + "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 + } + } + } + } + } + }, + "delete": { + "description": "Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.", + "tags": ["Collections"], + "summary": "Delete collection bookmark by details", + "parameters": [ + { + "in": "path", + "name": "collectionId", + "schema": { + "type": "string", + "description": "The Id of the collection to be deleted.", + "example": "cmkwbc0mo000bb0s0agvl9c6c" + }, + "required": true, + "description": "The Id of the collection to be deleted." + }, + { + "in": "query", + "name": "lastMutationAt", + "schema": { + "type": "number", + "format": "float", + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.", + "example": 1731636500303 + }, + "required": true, + "description": "The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control." + } + ], + "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 + } + } + } + }, + "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": { + "anyOf": [ + { + "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 }, + "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", + "example": 4 + } + }, + "required": ["key", "verseNumber", "mushaf"], + "additionalProperties": false, + "title": "Ayah" }, - "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": "object", + "properties": { + "key": { + "type": "integer", + "description": "Surah, Juz or page number." + }, + "type": { + "type": "string", + "enum": ["juz", "page", "surah"], + "description": "The bookmark type.", + "example": "surah" + }, + "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", + "example": 4 + } }, - "type": { "type": "string", "example": "gateway_timeout" }, - "success": { "type": "boolean", "example": false } + "required": ["key", "mushaf"], + "additionalProperties": false, + "title": "Surah, Juz, Or Page" }, - "additionalProperties": false - } + { + "type": "object", + "properties": { + "bookmarkId": { + "type": "string", + "description": "The Id of the bookmark to be deleted.", + "example": "cmkwbc0mo000ab0s0ddad6f04" + } + }, + "required": ["bookmarkId"], + "additionalProperties": false, + "title": "Bookmark ID" + } + ], + "title": "input" } } } @@ -2041,7 +2456,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmku2pw2b0009pdjq26tddi7u" + "example": "cmkwbc0m10009b0s0d05fapzk" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2163,6 +2578,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -2301,7 +2762,7 @@ "name": "collectionId", "schema": { "type": "string", - "example": "cmku2pw36000cpdjqfahw9b56" + "example": "cmkwbc0ng000eb0s04gn2b009" } }, { @@ -2346,7 +2807,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -2357,7 +2818,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -2389,11 +2850,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -2762,6 +3223,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -2903,7 +3410,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmku2pw2i000apdjqae7igz3n" + "example": "cmkwbc0mu000cb0s0cm6n09p7" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2914,7 +3421,7 @@ "schema": { "type": "string", "description": "The Id of the bookmark to be deleted.", - "example": "cmku2pw2i000bpdjqeuau0kl3" + "example": "cmkwbc0mu000db0s005p84503" }, "required": true, "description": "The Id of the bookmark to be deleted." @@ -3036,6 +3543,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -3224,7 +3777,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -3235,7 +3788,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -3258,11 +3811,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -3664,6 +4217,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -3855,7 +4454,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -3867,7 +4466,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -3891,11 +4490,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -4128,7 +4727,7 @@ "schema": { "type": "string", "description": "The id of the bookmark to be deleted.", - "example": "cmku2pvzi0006pdjq9cai8zg8" + "example": "cmkwbc0j40006b0s0gh8bh75y" }, "required": true, "description": "The id of the bookmark to be deleted." @@ -4245,7 +4844,53 @@ "type": { "type": "string", "example": "not_found" }, "success": { "type": "boolean", "example": false } }, - "additionalProperties": false + "additionalProperties": false + } + } + } + }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } } } } @@ -4446,11 +5091,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -5019,7 +5664,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -5031,7 +5676,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -6683,7 +7328,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -6694,7 +7339,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -6717,11 +7362,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -6958,7 +7603,8 @@ "QURAN_PAGES", "QURAN_RANGE", "COURSE", - "QURAN_READING_PROGRAM" + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" ], "description": "The type of the goal.", "example": "QURAN_TIME" @@ -7004,7 +7650,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmku2pvv00004pdjqb000bm4m" + "example": "cmkwbc0ec0004b0s040lfctn8" }, "date": { "type": "string", @@ -7352,7 +7998,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmku2pw4c000dpdjq8fb6hiz4" + "example": "cmkwbc0oi000fb0s04c737onv" }, "required": true, "description": "The id of the goal." @@ -7393,7 +8039,8 @@ "QURAN_PAGES", "QURAN_RANGE", "COURSE", - "QURAN_READING_PROGRAM" + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" ], "description": "The type of the goal.", "example": "QURAN_TIME" @@ -7422,7 +8069,12 @@ }, "category": { "type": "string", - "enum": ["QURAN", "COURSE", "QURAN_READING_PROGRAM"], + "enum": [ + "QURAN", + "COURSE", + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" + ], "description": "The category of the goal" } }, @@ -7666,7 +8318,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmku2pw4c000dpdjq8fb6hiz4" + "example": "cmkwbc0oi000fb0s04c737onv" }, "required": true, "description": "The id of the goal." @@ -7676,7 +8328,12 @@ "name": "category", "schema": { "type": "string", - "enum": ["QURAN", "COURSE", "QURAN_READING_PROGRAM"], + "enum": [ + "QURAN", + "COURSE", + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" + ], "description": "The category of the goal" }, "required": true, @@ -7960,7 +8617,8 @@ "QURAN_PAGES", "QURAN_RANGE", "COURSE", - "QURAN_READING_PROGRAM" + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" ], "description": "The type of the goal.", "example": "QURAN_TIME" @@ -7989,7 +8647,12 @@ }, "category": { "type": "string", - "enum": ["QURAN", "COURSE", "QURAN_READING_PROGRAM"], + "enum": [ + "QURAN", + "COURSE", + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" + ], "description": "The category of the goal" } }, @@ -8014,7 +8677,7 @@ "id": { "type": "string", "description": "The id of the goal.", - "example": "cmku2pw4c000dpdjq8fb6hiz4" + "example": "cmkwbc0oi000fb0s04c737onv" } }, "required": ["id"], @@ -8247,7 +8910,8 @@ "QURAN_PAGES", "QURAN_RANGE", "COURSE", - "QURAN_READING_PROGRAM" + "QURAN_READING_PROGRAM", + "RAMADAN_CHALLENGE" ], "description": "The type of the goal.", "example": "QURAN_TIME" @@ -8641,7 +9305,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -8652,7 +9316,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -8674,7 +9338,7 @@ "id": { "type": "string", "description": "The id of the streak.", - "example": "cmku2pwch000fpdjqbtmhe78f" + "example": "cmkwbc0zd000hb0s04j4j2nuj" }, "startDate": { "type": "string", @@ -8715,11 +9379,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -9581,7 +10245,7 @@ "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": "cmku2pvui0000pdjqec4ug7py" + "example": "cmkwbc0dr0000b0s0fboz3anv" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -9592,7 +10256,7 @@ "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": "cmku2pvuj0001pdjqgbvqbbqw" + "example": "cmkwbc0ds0001b0s01bxvcw79" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -9614,7 +10278,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmku2pvv00004pdjqb000bm4m" + "example": "cmkwbc0ec0004b0s040lfctn8" }, "date": { "type": "string", @@ -9738,11 +10402,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -10466,11 +11130,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -10936,6 +11600,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -11174,11 +11884,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmku2pvuj0002pdjqei7wcrwp" + "example": "cmkwbc0ds0002b0s0aeub15nr" }, "endCursor": { "type": "string", - "example": "cmku2pvuj0003pdjq75t5g9e7" + "example": "cmkwbc0ds0003b0s0a2whdvgb" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -12848,6 +13558,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -13106,6 +13862,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -13402,6 +14204,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -13565,12 +14413,12 @@ "name": "metadataOnly", "schema": { "type": "boolean", - "description": "When true, only returns lastMutationAt without mutations.", + "description": "When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }.", "example": true, "default": false }, "required": false, - "description": "When true, only returns lastMutationAt without mutations." + "description": "When true, returns only the lastMutationAt timestamp without fetching actual mutations. This is significantly faster (single DB query vs multiple joins) and ideal for: 1) Checking if new data exists before performing a full sync, 2) Implementing periodic background polling to detect changes, 3) Recovering the current lastMutationAt if the client missed the X-Mutation-At header from a previous successful mutation response. Response will only contain { lastMutationAt: number }." }, { "in": "query", @@ -13828,6 +14676,52 @@ } } }, + "409": { + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { "type": "boolean", "example": false }, + "error": { + "type": "object", + "properties": { + "code": { + "type": "string", + "example": "OutOfSyncError" + }, + "message": { + "type": "string", + "example": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + } + } + }, + "examples": { + "Out of sync": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "Invalid lastMutationAt, please re-sync your data and try again." + } + } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } + } + } + } + } + }, "422": { "description": "Validation Error. The request includes one or more invalid params. Please check the request params and try again.", "content": { @@ -14258,7 +15152,7 @@ } }, "409": { - "description": "Out of Sync Error. The client lastMutationAt does not match server state.", + "description": "Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.", "content": { "application/json": { "schema": { @@ -14289,6 +15183,15 @@ "message": "Invalid lastMutationAt, please re-sync your data and try again." } } + }, + "First sync - wrong lastMutationAt": { + "value": { + "success": false, + "error": { + "code": "OutOfSyncError", + "message": "First sync detected. Please use lastMutationAt=-1 for initial sync." + } + } } } } From 7579cbcad21349f1e1a4d5ebbbfe874fa492b21d Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Tue, 27 Jan 2026 15:13:21 +0700 Subject: [PATCH 5/9] Add sync scope --- docs/user_related_apis_versioned/scopes.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/user_related_apis_versioned/scopes.mdx b/docs/user_related_apis_versioned/scopes.mdx index 7647d9be..d85dfaef 100644 --- a/docs/user_related_apis_versioned/scopes.mdx +++ b/docs/user_related_apis_versioned/scopes.mdx @@ -162,3 +162,9 @@ granting access to the scopes your app is requesting first. | note.update | Update your notes | | note.delete | Delete your notes | | note.publish | Publish your notes | + +## Sync + +| Scope | Description | +| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| sync | Sync your data across devices. Required for the sync endpoints (`GET /v1/sync`, `POST /v1/sync`) to pull and push mutations for bookmarks, collections, and notes. | From 1f1768ad361c3b2d446b0dc489a42cccf5e2c566 Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Tue, 27 Jan 2026 15:49:42 +0700 Subject: [PATCH 6/9] Improve docs --- docs/tutorials/sync/_category_.json | 8 + docs/tutorials/sync/getting-started.mdx | 149 ++++++++++++++++++ docs/tutorials/sync/handling-conflicts.mdx | 144 +++++++++++++++++ .../tutorials/sync/offline-first-patterns.mdx | 136 ++++++++++++++++ sidebars.js | 51 +++++- 5 files changed, 486 insertions(+), 2 deletions(-) create mode 100644 docs/tutorials/sync/_category_.json create mode 100644 docs/tutorials/sync/getting-started.mdx create mode 100644 docs/tutorials/sync/handling-conflicts.mdx create mode 100644 docs/tutorials/sync/offline-first-patterns.mdx diff --git a/docs/tutorials/sync/_category_.json b/docs/tutorials/sync/_category_.json new file mode 100644 index 00000000..31457c02 --- /dev/null +++ b/docs/tutorials/sync/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Offline-first Sync", + "position": 2, + "link": { + "type": "generated-index", + "description": "Learn how to implement offline-first data synchronization for mobile apps using the Quran.Foundation Sync API." + } +} diff --git a/docs/tutorials/sync/getting-started.mdx b/docs/tutorials/sync/getting-started.mdx new file mode 100644 index 00000000..0a11ec69 --- /dev/null +++ b/docs/tutorials/sync/getting-started.mdx @@ -0,0 +1,149 @@ +--- +id: getting-started +title: Getting Started with Data Sync +sidebar_label: Getting Started +sidebar_position: 1 +--- + +# Getting Started with Data Sync + +The Quran.Foundation Sync API enables **offline-first mobile applications** to synchronize user data +across devices. This guide covers the core concepts and helps you implement your first sync flow. + +## Overview + +The Sync Layer provides: + +1. **Pull Changes** — Fetch all mutations (creates, updates, deletes) that occurred after a timestamp +2. **Push Changes** — Batch-submit local mutations made while offline +3. **Conflict Detection** — Prevents data conflicts using `lastMutationAt` timestamps + +```mermaid +sequenceDiagram + participant Client as Mobile Client
    (Offline-First) + participant Server as QF API Server + + Client->>Server: GET /v1/sync?mutationsSince=T + Server-->>Client: { mutations: [...], lastMutationAt } + + Note over Client: Apply server changes locally + + Client->>Server: POST /v1/sync
    { lastMutationAt, mutations } + Server-->>Client: { lastMutationAt, mutations } + + Note over Client: Update local lastMutationAt +``` + +## Prerequisites + +Before using the Sync API, ensure you have: + +1. **OAuth2 Client Credentials** — [Set up OAuth2](/docs/tutorials/oidc/getting-started-with-oauth2) for your app +2. **Required Scopes** — Request these scopes during authorization: + - [`sync`](/docs/user_related_apis_versioned/scopes#sync) — Required for all sync operations + - [`bookmark`](/docs/user_related_apis_versioned/scopes#bookmarks) — For syncing bookmarks + - [`collection`](/docs/user_related_apis_versioned/scopes#collections) — For syncing collections + - [`note`](/docs/user_related_apis_versioned/scopes#notes) — For syncing notes + +:::tip Scope Requirements +You only receive mutations for resources your token has access to. If you request [`sync`](/docs/user_related_apis_versioned/scopes#sync) + [`bookmark`](/docs/user_related_apis_versioned/scopes#bookmarks) but not [`collection`](/docs/user_related_apis_versioned/scopes#collections), you won't see collection changes. +::: + +## Supported Resources + +The Sync API currently tracks these resources: + +| Resource | Description | Required Scope | +| --------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | +| `BOOKMARK` | User bookmarks (ayah, surah, etc.) | [`bookmark`](/docs/user_related_apis_versioned/scopes#bookmarks) | +| `COLLECTION` | User collections | [`collection`](/docs/user_related_apis_versioned/scopes#collections) | +| `COLLECTION_BOOKMARK` | Bookmarks within collections | [`bookmark`](/docs/user_related_apis_versioned/scopes#bookmarks), [`collection`](/docs/user_related_apis_versioned/scopes#collections) | +| `NOTE` | User notes/reflections | [`note`](/docs/user_related_apis_versioned/scopes#notes) | + +## Key Concepts + +### lastMutationAt + +A Unix timestamp (milliseconds) tracking the most recent mutation for a user. This is your sync cursor. + +- **Stored locally** — Your app saves this after each successful sync +- **Sent with requests** — Include it to get only newer changes or validate your state +- **Updated by server** — The server assigns timestamps, ensuring consistent ordering + +### First Sync Behavior + +When a user has never synced before: + +| Scenario | Server Response | Client Action | +| ------------------ | ----------------------------- | ------------------------------------- | +| New user (no data) | `lastMutationAt: -1` | Store `-1`, ready for first mutation | +| First mutation | Send `lastMutationAt=-1` | Server accepts, returns new timestamp | +| Existing user | `lastMutationAt: ` | Store timestamp, fetch mutations | + +:::warning First Sync Requirement +For a user's very first mutation via `POST /v1/sync`, you **must** send `lastMutationAt=-1`. Any other value will be rejected. +::: + +## Quick Start: Your First Sync + +```mermaid +flowchart TD + A[Start] --> B["GET /v1/sync?mutationsSince=0&metadataOnly=true"] + B --> C{lastMutationAt?} + C -->|"-1 (new user)"| D["Store lastMutationAt = -1"] + C -->|"timestamp (existing user)"| E["GET /v1/sync?mutationsSince=0"] + E --> F["Apply mutations locally"] + F --> G["Store lastMutationAt"] + D --> H{User makes changes offline?} + G --> H + H -->|Yes| I["POST /v1/sync?lastMutationAt=T
    with mutations array"] + I --> J["Update lastMutationAt from response"] + J --> K[Done] + H -->|No| K +``` + +### Step 1: Check Sync Status + +First, check if the user has any existing data using `metadataOnly=true`. This returns only `lastMutationAt` without fetching mutations. + +- `lastMutationAt: -1` means new user with no data +- Any positive number means existing data exists + +### Step 2: Pull Existing Data + +If the user has data (`lastMutationAt > -1`), fetch all mutations and apply them locally. Store the `lastMutationAt` value for future requests. + +### Step 3: Push Local Changes + +When the user creates data offline, push mutations to the server. Update your local `lastMutationAt` from the response. + +### API References + +- [GET /v1/sync (Get mutations)](/docs/user_related_apis_versioned/get-mutations) +- [POST /v1/sync (Sync local mutations)](/docs/user_related_apis_versioned/sync-local-mutations) +- [POST /v1/bookmarks (Add bookmark)](/docs/user_related_apis_versioned/add-user-bookmark) — for bookmark field requirements + +## Using metadataOnly for Efficiency + +The `metadataOnly=true` parameter returns only the `lastMutationAt` without fetching mutations. Use it for: + +1. **Pre-sync checks** — Quickly check if new data exists before a full sync +2. **Background polling** — Efficiently detect changes without heavy payloads +3. **Recovering state** — If you missed the `X-Mutation-At` header from a previous response + +This is significantly faster than a full sync (single DB query vs multiple joins). + +For the full request/response schema, see: + +- [GET /v1/sync (Get mutations)](/docs/user_related_apis_versioned/get-mutations) + +## Important Notes + +- **Mutation limits** — `POST /v1/sync` accepts a maximum of 100 mutations per request. +- **Mutation types** — `BOOKMARK` and `COLLECTION_BOOKMARK` support **CREATE** and **DELETE** only. `COLLECTION` and `NOTE` support **CREATE**, **UPDATE**, and **DELETE**. +- **Direct endpoints** — Direct mutation endpoints (e.g. `POST /v1/bookmarks`) also return the `X-Mutation-At` header for updating `lastMutationAt`. + +## Next Steps + +- [Handling Conflicts](./handling-conflicts) — Learn how to handle 409 errors and resolve conflicts +- [Offline-First Patterns](./offline-first-patterns) — Best practices for client-side architecture diff --git a/docs/tutorials/sync/handling-conflicts.mdx b/docs/tutorials/sync/handling-conflicts.mdx new file mode 100644 index 00000000..a214596a --- /dev/null +++ b/docs/tutorials/sync/handling-conflicts.mdx @@ -0,0 +1,144 @@ +--- +id: handling-conflicts +title: Handling Sync Conflicts +sidebar_label: Handling Conflicts +sidebar_position: 2 +--- + +# Handling Sync Conflicts + +When your client's `lastMutationAt` doesn't match the server's state, you'll receive a **409 Conflict** error. This guide explains when conflicts occur and how to resolve them. + +## When Conflicts Occur + +A 409 `OutOfSyncError` happens when: + +1. **Another device synced** — User made changes on a different device +2. **Concurrent mutations** — Server received mutations while you were offline +3. **Missed header** — Client didn't capture the `X-Mutation-At` response header +4. **First sync mismatch** — Sending wrong `lastMutationAt` for a new user + +```mermaid +sequenceDiagram + participant Phone as Phone A + participant Server as Server + participant Tablet as Tablet B + + Phone->>Server: POST /v1/sync?lastMutationAt=100 + Server-->>Phone: 200 OK, lastMutationAt=200 + + Note over Tablet: Tablet still has lastMutationAt=100 + + Tablet->>Server: POST /v1/sync?lastMutationAt=100 + Server-->>Tablet: 409 Conflict ❌ + + Note over Tablet: Must re-sync first! +``` + +## The 409 Error Response + +When a conflict occurs, the server responds: + +- **Error code:** `OutOfSyncError` +- **Message:** `Invalid lastMutationAt, please re-sync your data and try again.` + +**HTTP Status:** `409 Conflict` + +### First-Sync Variant + +If this is a new user's first sync and you send the wrong `lastMutationAt`: + +- **Error code:** `OutOfSyncError` +- **Message:** `First sync detected. Please use lastMutationAt=-1 for initial sync.` + +## Conflict Resolution Flow + +Here's the standard recovery pattern: + +```mermaid +sequenceDiagram + participant Client + participant Server + + Client->>Server: POST /v1/sync?lastMutationAt=T1 + Server-->>Client: 409 Conflict + + Note over Client: Start recovery... + + Client->>Server: GET /v1/sync?mutationsSince=T1 + Server-->>Client: { mutations: [...], lastMutationAt: T_server } + + Client->>Client: Apply server changes locally + Client->>Client: Resolve any conflicts + + Client->>Server: POST /v1/sync?lastMutationAt=T_server + Server-->>Client: 200 OK { lastMutationAt: T_new } + + Note over Client: Sync complete ✓ +``` + +### Step-by-Step Recovery + +1. **Catch the 409 error** +2. **Fetch server changes** — `GET /v1/sync?mutationsSince=` +3. **Apply server mutations** to your local database +4. **Resolve conflicts** if the same resource was modified both locally and remotely +5. **Retry your mutations** with the new `lastMutationAt` + +## Code Example + +For production-ready implementations, see the [SDK docs](/docs/sdk). + +## Conflict Resolution Strategies + +When the same resource is modified both locally and on the server, you need a strategy: + +### 1. Server Wins (Recommended for simplicity) + +Server changes always take precedence. Discard conflicting local changes. + +### 2. Client Wins + +Local changes always take precedence. Re-submit all local mutations. + +### 3. Last-Write Wins + +Compare timestamps and keep the most recent change. + +### 4. Merge (Complex) + +Combine changes field-by-field. Best for resources with independent fields. + +## Recovering lastMutationAt + +If your client loses track of `lastMutationAt` (e.g., app crash, missed header), use `metadataOnly`: + +This quickly retrieves the current `lastMutationAt` without fetching all mutations. + +See the full request/response schema in the API reference: + +- [GET /v1/sync (Get mutations)](/docs/user_related_apis_versioned/get-mutations) + +## Direct Mutation Endpoints + +When using direct mutation endpoints (e.g., `POST /v1/bookmarks`), the same conflict rules apply: + +1. Include `lastMutationAt` as a query parameter +2. Check for 409 responses +3. Update `lastMutationAt` from the `X-Mutation-At` response header + +:::tip Always Capture the Header +Store the `X-Mutation-At` header value after every successful mutation. If you miss it, use `metadataOnly=true` to recover. +::: + +## Best Practices + +1. **Always handle 409** — Don't assume sync will succeed +2. **Queue mutations locally** — Store pending changes before attempting sync +3. **Implement retry logic** — Automatic recovery improves UX +4. **Choose a consistent strategy** — Pick one conflict resolution approach and stick with it +5. **Log conflicts** — Track how often conflicts occur to optimize your sync frequency + +## Next Steps + +- [Offline-First Patterns](./offline-first-patterns) — Architecture for robust offline support diff --git a/docs/tutorials/sync/offline-first-patterns.mdx b/docs/tutorials/sync/offline-first-patterns.mdx new file mode 100644 index 00000000..46e1c17c --- /dev/null +++ b/docs/tutorials/sync/offline-first-patterns.mdx @@ -0,0 +1,136 @@ +--- +id: offline-first-patterns +title: Offline-First Architecture Patterns +sidebar_label: Offline-First Patterns +sidebar_position: 3 +--- + +# Offline-First Architecture Patterns + +This guide covers best practices for building mobile apps that work seamlessly offline and sync reliably when connectivity is restored. + +:::tip SDK Implementations +For production-ready implementations, see our [SDK docs](/docs/sdk). +::: + +## Core Principles + +1. **Local-first** — All reads and writes happen against local storage first +2. **Optimistic UI** — Show changes immediately, sync in background +3. **Queue mutations** — Store pending changes for later sync +4. **Graceful degradation** — App works fully offline, syncs when possible + +## Architecture Overview + +```mermaid +flowchart TB + subgraph App["Mobile App"] + UI["UI
    (Reads/Writes)"] + DB["Local DB
    (SQLite/Room/CoreData)"] + subgraph Sync["Sync Engine"] + Queue["Mutation Queue"] + LMA["lastMutationAt"] + end + end + + subgraph Network["Network Layer"] + Conn["Connectivity Monitoring"] + end + + Server["QF API Server"] + + UI --> DB + DB <--> Sync + Sync --> Conn + Conn --> Server + Server -.-> DB +``` + +## Local Storage Design + +### Data Model + +Store synced resources with metadata: + +```typescript +interface LocalBookmark { + // Server fields + id: string; + key: number; + verseNumber?: number; + bookmarkType: string; + bookmarkGroup: string; + + // Sync metadata + syncStatus: "synced" | "pending_create" | "pending_update" | "pending_delete"; + localUpdatedAt: number; // Local timestamp for conflict detection + serverTimestamp?: number; // From mutation response +} +``` + +### Sync Metadata Table + +Track global sync state: + +```typescript +interface SyncMetadata { + lastMutationAt: number; // Server's latest mutation timestamp + lastSyncAttempt: number; // When we last tried to sync + lastSuccessfulSync: number; // When sync last succeeded + pendingMutationCount: number; // Mutations waiting to sync +} +``` + +## Mutation Queue + +Queue all local changes for reliable sync: + +```typescript +interface QueuedMutation { + id: string; // Local unique ID + type: "CREATE" | "UPDATE" | "DELETE"; + resource: string; + resourceId?: string; // For UPDATE/DELETE + data: Record; + createdAt: number; // When queued + retryCount: number; // For exponential backoff + lastError?: string; // Track failures +} +``` + +## Sync Engine + +Your sync engine should follow a **pull → apply → push** cycle and handle 409 conflicts by re-syncing before retrying local mutations. For a production-ready implementation, see the [SDK docs](/docs/sdk). + +## Connectivity Handling + +Monitor connectivity and trigger sync when connectivity is restored. Use `metadataOnly=true` for lightweight polling to detect server changes. + +## Optimistic Updates + +Update UI immediately, sync in background: + +Apply local changes immediately, then enqueue mutations for sync. When the server responds, reconcile local IDs and timestamps with server-assigned values. + +### Handling Sync Results + +When the server returns mutation results, update local records with server IDs and timestamps, then dequeue the synced mutations. + +## Error Handling & Retry + +Implement exponential backoff for failed syncs: + +Use exponential backoff, cap retry attempts, and persist failures so users can recover changes later. + +## Best Practices Summary + +| Practice | Description | +| ----------------------- | ---------------------------------------- | +| **Local-first** | Always read/write locally first | +| **Queue everything** | Never lose mutations - queue before sync | +| **Optimistic UI** | Show changes immediately | +| **Handle offline** | App should work without network | +| **Batch syncs** | Minimize network requests | +| **Exponential backoff** | Don't hammer the server on failures | +| **Background sync** | Keep data fresh automatically | +| **Conflict strategy** | Pick one approach and be consistent | diff --git a/sidebars.js b/sidebars.js index cbc446fb..e75eff91 100644 --- a/sidebars.js +++ b/sidebars.js @@ -56,9 +56,56 @@ const sidebars = { ], }, { - type: "autogenerated", - dirName: "tutorials/oidc", + type: "category", + label: "📱 Mobile Apps", + link: { + type: "generated-index", + description: "Build offline-first mobile apps with authentication and data sync capabilities.", + }, + items: [ + { + type: "category", + label: "Authentication", + link: { + type: "generated-index", + description: "Integrate OAuth2/OpenID Connect authentication in your mobile app.", + }, + items: [ + "tutorials/oidc/mobile-apps/android", + "tutorials/oidc/mobile-apps/iOS", + "tutorials/oidc/mobile-apps/react-native", + ], + }, + { + type: "category", + label: "Offline-first Sync", + link: { + type: "generated-index", + description: "Implement offline-first data synchronization for your mobile app.", + }, + items: [ + "tutorials/sync/getting-started", + "tutorials/sync/handling-conflicts", + "tutorials/sync/offline-first-patterns", + ], + }, + ], + }, + { + type: "category", + label: "⚡ Quick Start", + link: { + type: "generated-index", + description: "Get started with OAuth2 authentication for Quran.Foundation APIs.", + }, + items: [ + "tutorials/oidc/getting-started-with-oauth2", + "tutorials/oidc/user-apis-quickstart", + ], }, + "tutorials/oidc/openid-connect", + "tutorials/oidc/example-integration", + "tutorials/oidc/client-setup", ], APIsSidebar: [ { From 922808f11077f5904787a13e18f1dce75eaaab6f Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Tue, 27 Jan 2026 15:55:49 +0700 Subject: [PATCH 7/9] Improve docs --- docs/tutorials/oidc/example-integration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/oidc/example-integration.mdx b/docs/tutorials/oidc/example-integration.mdx index 0497e85d..3d4d1fe1 100644 --- a/docs/tutorials/oidc/example-integration.mdx +++ b/docs/tutorials/oidc/example-integration.mdx @@ -70,7 +70,7 @@ const response = await fetch( "x-auth-token": access_token, "x-client-id": process.env.CLIENT_ID, }, - } + }, ); const bookmarks = await response.json(); ``` @@ -233,5 +233,5 @@ fly deploy ## Next Steps - **[Full OAuth2 Guide](/docs/tutorials/oidc/getting-started-with-oauth2)** — Detailed walkthrough with AI prompts -- **[Mobile Apps](/docs/category/mobile-apps)** — iOS, Android, React Native guides +- **[SDK](/docs/sdk)** — Client SDK for mobile and web apps - **[User APIs Reference](/docs/category/user-related-apis)** — All available endpoints From a3606c7cd2e8848fe29aa8051d1460fbba35f739 Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Mon, 2 Feb 2026 05:41:23 +0700 Subject: [PATCH 8/9] update docs --- docs/tutorials/sync/getting-started.mdx | 46 ++++++++++++------- docs/tutorials/sync/handling-conflicts.mdx | 6 +-- .../tutorials/sync/offline-first-patterns.mdx | 18 +++++--- 3 files changed, 44 insertions(+), 26 deletions(-) diff --git a/docs/tutorials/sync/getting-started.mdx b/docs/tutorials/sync/getting-started.mdx index 0a11ec69..1b1efe55 100644 --- a/docs/tutorials/sync/getting-started.mdx +++ b/docs/tutorials/sync/getting-started.mdx @@ -28,7 +28,7 @@ sequenceDiagram Note over Client: Apply server changes locally - Client->>Server: POST /v1/sync
    { lastMutationAt, mutations } + Client->>Server: POST /v1/sync?lastMutationAt=T
    { mutations } Server-->>Client: { lastMutationAt, mutations } Note over Client: Update local lastMutationAt @@ -40,7 +40,7 @@ Before using the Sync API, ensure you have: 1. **OAuth2 Client Credentials** — [Set up OAuth2](/docs/tutorials/oidc/getting-started-with-oauth2) for your app 2. **Required Scopes** — Request these scopes during authorization: - - [`sync`](/docs/user_related_apis_versioned/scopes#sync) — Required for all sync operations + - [`sync`](/docs/user_related_apis_versioned/scopes#sync) — Required for `GET /v1/sync` and `POST /v1/sync` - [`bookmark`](/docs/user_related_apis_versioned/scopes#bookmarks) — For syncing bookmarks - [`collection`](/docs/user_related_apis_versioned/scopes#collections) — For syncing collections - [`note`](/docs/user_related_apis_versioned/scopes#notes) — For syncing notes @@ -51,7 +51,7 @@ You only receive mutations for resources your token has access to. If you reques ## Supported Resources -The Sync API currently tracks these resources: +The Sync API currently tracks these resources. All `/v1/sync` calls also require the [`sync`](/docs/user_related_apis_versioned/scopes#sync) scope. | Resource | Description | Required Scope | | --------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | @@ -60,6 +60,11 @@ The Sync API currently tracks these resources: | `COLLECTION_BOOKMARK` | Bookmarks within collections | [`bookmark`](/docs/user_related_apis_versioned/scopes#bookmarks), [`collection`](/docs/user_related_apis_versioned/scopes#collections) | | `NOTE` | User notes/reflections | [`note`](/docs/user_related_apis_versioned/scopes#notes) | +:::note Resource IDs vs composite keys +For `BOOKMARK`, `COLLECTION`, and `NOTE`, sync mutations include a single `resourceId`. +For `COLLECTION_BOOKMARK`, there is no single ID; use `data.collectionId` and `data.bookmarkId` instead and omit `resourceId` in your mutation. +::: + ## Key Concepts ### lastMutationAt @@ -72,13 +77,13 @@ A Unix timestamp (milliseconds) tracking the most recent mutation for a user. Th ### First Sync Behavior -When a user has never synced before: +When a user has never synced before (no `lastMutationAt` stored on the server): -| Scenario | Server Response | Client Action | -| ------------------ | ----------------------------- | ------------------------------------- | -| New user (no data) | `lastMutationAt: -1` | Store `-1`, ready for first mutation | -| First mutation | Send `lastMutationAt=-1` | Server accepts, returns new timestamp | -| Existing user | `lastMutationAt: ` | Store timestamp, fetch mutations | +| Scenario | Server Response | Client Action | +| ------------------------------- | ----------------------------- | ------------------------------------------------- | +| No sync history yet | `lastMutationAt: -1` | Store `-1`, treat as first-sync state | +| First mutation from this device | Send `lastMutationAt=-1` | Server accepts, returns new timestamp | +| User already has sync history | `lastMutationAt: ` | Store timestamp, fetch mutations since `0` (or T) | :::warning First Sync Requirement For a user's very first mutation via `POST /v1/sync`, you **must** send `lastMutationAt=-1`. Any other value will be rejected. @@ -90,13 +95,13 @@ For a user's very first mutation via `POST /v1/sync`, you **must** send `lastMut flowchart TD A[Start] --> B["GET /v1/sync?mutationsSince=0&metadataOnly=true"] B --> C{lastMutationAt?} - C -->|"-1 (new user)"| D["Store lastMutationAt = -1"] + C -->|"-1 (first-sync state)"| D["Store lastMutationAt = -1"] C -->|"timestamp (existing user)"| E["GET /v1/sync?mutationsSince=0"] E --> F["Apply mutations locally"] F --> G["Store lastMutationAt"] D --> H{User makes changes offline?} G --> H - H -->|Yes| I["POST /v1/sync?lastMutationAt=T
    with mutations array"] + H -->|Yes| I["POST /v1/sync?lastMutationAt=-1 (first time)
    or lastMutationAt=T (later)
    with mutations array"] I --> J["Update lastMutationAt from response"] J --> K[Done] H -->|No| K @@ -104,9 +109,9 @@ flowchart TD ### Step 1: Check Sync Status -First, check if the user has any existing data using `metadataOnly=true`. This returns only `lastMutationAt` without fetching mutations. +First, check if the user has any existing data using `metadataOnly=true`. This returns only `lastMutationAt` without fetching mutations. (You still need to pass `mutationsSince`, even when `metadataOnly=true`.) -- `lastMutationAt: -1` means new user with no data +- `lastMutationAt: -1` means no sync history yet (first-sync state) - Any positive number means existing data exists ### Step 2: Pull Existing Data @@ -115,7 +120,7 @@ If the user has data (`lastMutationAt > -1`), fetch all mutations and apply them ### Step 3: Push Local Changes -When the user creates data offline, push mutations to the server. Update your local `lastMutationAt` from the response. +When the user creates data offline, push mutations to the server using `POST /v1/sync?lastMutationAt=...`. Update your local `lastMutationAt` from the response. ### API References @@ -137,11 +142,20 @@ For the full request/response schema, see: - [GET /v1/sync (Get mutations)](/docs/user_related_apis_versioned/get-mutations) +## Filtering & Pagination + +`GET /v1/sync` supports resource filtering and pagination: + +- `resources=BOOKMARK,COLLECTION` limits results to those resources +- `limit` and `page` paginate results (max `limit` is 1000) +- Continue fetching pages until `hasMore=false` + +When `metadataOnly=true`, the response includes only `lastMutationAt` (no pagination fields). + ## Important Notes - **Mutation limits** — `POST /v1/sync` accepts a maximum of 100 mutations per request. -- **Mutation types** — `BOOKMARK` and `COLLECTION_BOOKMARK` support **CREATE** and **DELETE** only. `COLLECTION` and `NOTE` support **CREATE**, **UPDATE**, and **DELETE**. -- **Direct endpoints** — Direct mutation endpoints (e.g. `POST /v1/bookmarks`) also return the `X-Mutation-At` header for updating `lastMutationAt`. +- **Direct endpoints** — Direct mutation endpoints (e.g. `POST /v1/bookmarks`) require `lastMutationAt` as a query param and return the `X-Mutation-At` header for updating `lastMutationAt`. ## Next Steps diff --git a/docs/tutorials/sync/handling-conflicts.mdx b/docs/tutorials/sync/handling-conflicts.mdx index a214596a..dba477da 100644 --- a/docs/tutorials/sync/handling-conflicts.mdx +++ b/docs/tutorials/sync/handling-conflicts.mdx @@ -7,7 +7,7 @@ sidebar_position: 2 # Handling Sync Conflicts -When your client's `lastMutationAt` doesn't match the server's state, you'll receive a **409 Conflict** error. This guide explains when conflicts occur and how to resolve them. +When your client's `lastMutationAt` doesn't exactly match the server's state, you'll receive a **409 Conflict** error. This guide explains when conflicts occur and how to resolve them. ## When Conflicts Occur @@ -71,7 +71,7 @@ sequenceDiagram Client->>Client: Apply server changes locally Client->>Client: Resolve any conflicts - Client->>Server: POST /v1/sync?lastMutationAt=T_server + Client->>Server: POST /v1/sync?lastMutationAt=T_server
    { mutations: [...] } Server-->>Client: 200 OK { lastMutationAt: T_new } Note over Client: Sync complete ✓ @@ -113,7 +113,7 @@ Combine changes field-by-field. Best for resources with independent fields. If your client loses track of `lastMutationAt` (e.g., app crash, missed header), use `metadataOnly`: -This quickly retrieves the current `lastMutationAt` without fetching all mutations. +This quickly retrieves the current `lastMutationAt` without fetching all mutations. You still need to pass `mutationsSince` in the request. See the full request/response schema in the API reference: diff --git a/docs/tutorials/sync/offline-first-patterns.mdx b/docs/tutorials/sync/offline-first-patterns.mdx index 46e1c17c..601e1900 100644 --- a/docs/tutorials/sync/offline-first-patterns.mdx +++ b/docs/tutorials/sync/offline-first-patterns.mdx @@ -50,16 +50,14 @@ flowchart TB ### Data Model -Store synced resources with metadata: +Store synced resources with metadata. Resource fields vary by type, so keep them in a data payload you can map into your domain model. ```typescript -interface LocalBookmark { +interface LocalResource> { // Server fields id: string; - key: number; - verseNumber?: number; - bookmarkType: string; - bookmarkGroup: string; + resource: "BOOKMARK" | "COLLECTION" | "COLLECTION_BOOKMARK" | "NOTE"; + data: TData; // Sync metadata syncStatus: "synced" | "pending_create" | "pending_update" | "pending_delete"; @@ -102,6 +100,12 @@ interface QueuedMutation { Your sync engine should follow a **pull → apply → push** cycle and handle 409 conflicts by re-syncing before retrying local mutations. For a production-ready implementation, see the [SDK docs](/docs/sdk). +### Pull → Apply → Push (with pagination) + +1. **Pull** — Call `GET /v1/sync?mutationsSince=T` and page through results (`page`/`limit`) until `hasMore=false`. +2. **Apply** — Apply mutations in timestamp order and update local records. +3. **Push** — Send queued mutations with `POST /v1/sync?lastMutationAt=T` and update `lastMutationAt` from the response. + ## Connectivity Handling Monitor connectivity and trigger sync when connectivity is restored. Use `metadataOnly=true` for lightweight polling to detect server changes. @@ -114,7 +118,7 @@ Apply local changes immediately, then enqueue mutations for sync. When the serve ### Handling Sync Results -When the server returns mutation results, update local records with server IDs and timestamps, then dequeue the synced mutations. +When the server returns mutation results, update local records with server IDs and timestamps, then dequeue the synced mutations. For direct mutation endpoints (e.g., `POST /v1/bookmarks`), read `X-Mutation-At` from the response header and persist it as your new `lastMutationAt`. ## Error Handling & Retry From cca632c56260b58b3e94763c6426f3d5e05708d0 Mon Sep 17 00:00:00 2001 From: Osama Sayed Date: Sat, 14 Feb 2026 11:59:57 +0700 Subject: [PATCH 9/9] updates --- .../1.0.0/add-collection-bookmark.api.mdx | 4 +- .../1.0.0/add-collection.api.mdx | 4 +- .../1.0.0/add-or-update-preference.api.mdx | 2 +- .../1.0.0/add-user-bookmark.api.mdx | 6 +- .../bulk-add-or-update-preferences.api.mdx | 4 +- .../1.0.0/comments-controller-create.api.mdx | 2 +- .../1.0.0/comments-controller-get.api.mdx | 2 +- .../1.0.0/create-a-goal.api.mdx | 4 +- .../1.0.0/delete-a-goal.api.mdx | 4 +- .../1.0.0/delete-bookmark.api.mdx | 4 +- ...ete-collection-bookmark-by-details.api.mdx | 4 +- .../delete-collection-bookmark-by-id.api.mdx | 4 +- .../1.0.0/delete-collection.api.mdx | 4 +- .../1.0.0/get-activity-days.api.mdx | 8 +- .../1.0.0/get-all-collection-items.api.mdx | 6 +- .../1.0.0/get-all-collections.api.mdx | 6 +- .../1.0.0/get-all-notes.api.mdx | 4 +- .../1.0.0/get-bookmark-collections.api.mdx | 6 +- .../1.0.0/get-bookmark.api.mdx | 6 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../1.0.0/get-collection-items-by-id.api.mdx | 6 +- .../1.0.0/get-notes-by-verse.api.mdx | 4 +- .../1.0.0/get-streaks.api.mdx | 6 +- .../1.0.0/get-todays-goal-plan.api.mdx | 4 +- .../1.0.0/get-user-bookmarks.api.mdx | 6 +- .../1.0.0/get-user-preferences.api.mdx | 4 +- .../1.0.0/get-user-reading-sessions.api.mdx | 6 +- .../1.0.0/posts-controller-create.api.mdx | 4 +- .../1.0.0/posts-controller-edit.api.mdx | 4 +- .../1.0.0/posts-controller-feed.api.mdx | 2 +- .../1.0.0/posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../1.0.0/rooms-controller-get-rooms.api.mdx | 4 +- .../1.0.0/tags-controller-find.api.mdx | 2 +- .../1.0.0/update-a-goal.api.mdx | 4 +- .../users-controller-edit-profile.api.mdx | 4 +- .../add-collection-bookmark.api.mdx | 4 +- .../add-collection.api.mdx | 4 +- .../add-or-update-preference.api.mdx | 2 +- .../add-user-bookmark.api.mdx | 6 +- .../bulk-add-or-update-preferences.api.mdx | 4 +- .../comments-controller-create.api.mdx | 2 +- .../comments-controller-get.api.mdx | 2 +- .../create-a-goal.api.mdx | 4 +- .../delete-a-goal.api.mdx | 4 +- .../delete-bookmark.api.mdx | 4 +- ...ete-collection-bookmark-by-details.api.mdx | 4 +- .../delete-collection-bookmark-by-id.api.mdx | 4 +- .../delete-collection.api.mdx | 4 +- .../get-activity-days.api.mdx | 8 +- .../get-all-collection-items.api.mdx | 6 +- .../get-all-collections.api.mdx | 6 +- .../get-all-notes.api.mdx | 4 +- .../get-bookmark-collections.api.mdx | 6 +- .../get-bookmark.api.mdx | 6 +- ...-bookmarks-within-a-range-of-ayahs.api.mdx | 4 +- .../get-collection-items-by-id.api.mdx | 6 +- .../get-notes-by-verse.api.mdx | 4 +- .../get-streaks.api.mdx | 6 +- .../get-todays-goal-plan.api.mdx | 4 +- .../get-user-bookmarks.api.mdx | 6 +- .../get-user-preferences.api.mdx | 4 +- .../get-user-reading-sessions.api.mdx | 6 +- .../posts-controller-create.api.mdx | 4 +- .../posts-controller-edit.api.mdx | 4 +- .../posts-controller-feed.api.mdx | 2 +- .../posts-controller-find-one.api.mdx | 2 +- .../posts-controller-get-all-comment.api.mdx | 2 +- .../posts-controller-get-comments.api.mdx | 2 +- ...controller-get-loggedin-user-posts.api.mdx | 2 +- ...s-controller-get-my-posts-by-verse.api.mdx | 2 +- .../posts-controller-get-user-post.api.mdx | 2 +- .../rooms-controller-get-rooms.api.mdx | 4 +- .../tags-controller-find.api.mdx | 2 +- .../update-a-goal.api.mdx | 4 +- .../users-controller-edit-profile.api.mdx | 4 +- openAPI/user-related-apis/v1.json | 223 ++++++++++++------ 81 files changed, 313 insertions(+), 230 deletions(-) diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx index cc808eda..6e409fba 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkwbc0lu0008b0s0ax83876g"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmllufwb7000842jqdmx1fglm"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    +
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx index d22507da..d08ed54b 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx index 1e2706ca..cfb44483 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-or-update-preference.api.mdx @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one user preferences group like favorite Tafsirs or translations. -
    Query Parameters
    Request Body
      anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
    +
    Query Parameters
    Request Body
      anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx index 3559d11b..a8f5b838 100644 --- a/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"isReading":true,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark by details. -
    Query Parameters
    Request Body
      anyOf
    +
    Query Parameters
    Request Body
      anyOf
    Request has been handled successfully. @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx b/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx index 6b8069bb..6f95231a 100644 --- a/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/bulk-add-or-update-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Add or update one or more user preferences groups like favorite Ta sidebar_label: "Bulk add or update preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"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,"quranFont":"code_v1","mushafLines":"16_lines"},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"},"userHasCustomised":{"userHasCustomised":false}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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},"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"],"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,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"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,"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}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one or more user preferences groups like favorite Tafsirs and translations. -
    Query Parameters
    Request Body
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    +
    Query Parameters
    Request Body
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx index 7d984271..b0cd0cfd 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx index 4848d9d7..94fdc373 100644 --- a/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Parent comment not found diff --git a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx index 535f27c1..7bd98e14 100644 --- a/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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:10","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}}}},"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":"cmkwbc0oi000fb0s04c737onv"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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:10","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}}}},"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":"cmllufwdv000f42jqe7ukd4my"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx index 09b4768c..64c37214 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmllufwdv000f42jqe7ukd4my"},"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
    Path Parameters
    Query Parameters
    Header Parameters
    +
    Path Parameters
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx index 54871721..5e633bd6 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkwbc0j40006b0s0gh8bh75y"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmllufw83000642jqazgfho39"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx index 491b1dc1..284c22ce 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-details.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's detail sidebar_label: "Delete collection bookmark by details" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mo000bb0s0agvl9c6c"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}}},"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":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"},{"type":"object","required":["bookmarkId"],"additionalProperties":false,"title":"Bookmark ID"}],"title":"input"}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Delete collection bookmark by details","description":{"content":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"DELETE","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmllufwbz000b42jq1a29a6fn"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}}},"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":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"},{"type":"object","required":["bookmarkId"],"additionalProperties":false,"title":"Bookmark ID"}],"title":"input"}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Delete collection bookmark by details","description":{"content":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"DELETE","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    +
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx index c88b4843..498a6eed 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mu000cb0s0cm6n09p7"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkwbc0mu000db0s005p84503"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmllufwc7000c42jqgppy4l7i"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmllufwc7000d42jqcssd1xyn"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx index acb2544f..d43d8742 100644 --- a/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0m10009b0s0d05fapzk"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmllufwbe000942jq2gbqaan5"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx index 192454a5..79dd0d24 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":"cmllufw2m000442jqb9o141br"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
      • ranges object
      +
      Schema
        data object[]
      • Array [
        • ranges object
        The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
      • ]
        • pagination object
      +
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx index 76fffe0f..425928e3 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx index 9c3ac0f3..b47db138 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx index 8396e663..b0829a74 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx index 4d0e7d3a..055b93dc 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":"object","properties":{"id":{"type":"string","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx index 2844c2e2..d0a4046c 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"in":"query","name":"isReading","schema":{"type":"boolean","description":"Whether to fetch the reading bookmark"},"required":false,"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},"required":false,"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"},"required":false,"description":"The bookmark type."},{"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","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":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"Whether to fetch the reading bookmark","type":"text/plain"},"key":"isReading","value":""},{"disabled":false,"description":{"content":"Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get a bookmark by details -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx index 56d92496..6862813a 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx index 3f9ca8e5..60f41723 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkwbc0ng000eb0s04gn2b009"}},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmllufwcx000e42jqbbko1239"}},{"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx index fc1194df..e0b34ea8 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx index c6b28611..0e6a420d 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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 streak.","example":"cmkwbc0zd000hb0s04j4j2nuj"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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 streak.","example":"cmllufwnz000h42jq9fhh3626"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx index 95435625..99be20d7 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"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":"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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"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":"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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmllufw2m000442jqb9o141br"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx index 4d70127e..abdb4208 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"Whether to fetch only the reading bookmark","type":"text/plain"},"key":"isReading","value":""},{"disabled":false,"description":{"content":"Filter by key (surah/juz/page number)","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx index 665984a2..bad181f3 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Get all user preferences like theme, favorite reciter, default lan sidebar_label: "Get user preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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},"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"],"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,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all user preferences like theme, favorite reciter, default language etc. Request has been handled successfully. -
    Schema
      data object
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    +
    Schema
      data object
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx index c972d36f..ae0c3a99 100644 --- a/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0yr000gb0s01wvy1ntj"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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","example":"cmllufwnf000g42jq7xsp5ndw"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx index 7b9f0d87..5b0e03b3 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:28.056Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-02-14T04:59:41.898Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx index 0f339c94..dacabf78 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:28.056Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-02-14T04:59:41.898Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx index 492314f2..cba95649 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx index e0525ce6..50451dc3 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx index 563707c4..1b34b1b0 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx index 56cdd332..97f88960 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx index 77c56933..f797480d 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx index 4fbf84d8..7780c4e8 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx index 76e63a6d..637255b0 100644 --- a/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/rooms-controller-get-rooms.api.mdx b/docs/user_related_apis_versioned/1.0.0/rooms-controller-get-rooms.api.mdx index 9bec8f7d..16f62558 100644 --- a/docs/user_related_apis_versioned/1.0.0/rooms-controller-get-rooms.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/rooms-controller-get-rooms.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve rooms the user has joined (joined-rooms) or manages as ad sidebar_label: "Get joined or managed rooms" hide_title: true hide_table_of_contents: true -api: {"operationId":"RoomsController_getRooms","description":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","parameters":[{"name":"query","required":false,"in":"query","description":"Search query for room names","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Rooms per page (default: 5)","schema":{"minimum":1,"maximum":5,"default":5,"type":"number"}}],"responses":{"200":{"description":"Rooms retrieved with pagination"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"get","path":"/v1/rooms/joined-rooms","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get joined or managed rooms","description":{"content":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","type":"text/plain"},"url":{"path":["v1","rooms","joined-rooms"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Search query for room names","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Page number (default: 1)","type":"text/plain"},"key":"page","value":""},{"disabled":false,"description":{"content":"Rooms per page (default: 5)","type":"text/plain"},"key":"limit","value":""}],"variable":[]},"method":"GET"}} +api: {"operationId":"RoomsController_getRooms","description":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","parameters":[{"name":"query","required":false,"in":"query","description":"Search query for room names","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Rooms per page (default: 5)","schema":{"minimum":1,"maximum":5,"default":5,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Sort order (default: NAME_ASC)","schema":{"enum":["NAME_ASC","NAME_DESC","LATEST_ACTIVITY"],"type":"string"}}],"responses":{"200":{"description":"Rooms retrieved with pagination"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"get","path":"/v1/rooms/joined-rooms","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get joined or managed rooms","description":{"content":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","type":"text/plain"},"url":{"path":["v1","rooms","joined-rooms"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Search query for room names","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Page number (default: 1)","type":"text/plain"},"key":"page","value":""},{"disabled":false,"description":{"content":"Rooms per page (default: 5)","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Sort order (default: NAME_ASC)","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination. -
    Query Parameters
    +
    Query Parameters
    Rooms retrieved with pagination diff --git a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx index 7fb62434..4c5f6f15 100644 --- a/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
    Schema
    • Array [
    • ]
    +
    Schema
    • Array [
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx index a5cc30ed..4a1855ab 100644 --- a/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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:10","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}}}},"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}}}},"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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmllufwdv000f42jqe7ukd4my"},"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:10","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}}}},"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}}}},"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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
    Path Parameters
    Query Parameters
    Header Parameters
    Request Body
      amount object
      +
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/docs/user_related_apis_versioned/1.0.0/users-controller-edit-profile.api.mdx b/docs/user_related_apis_versioned/1.0.0/users-controller-edit-profile.api.mdx index e5771bc4..1b83356c 100644 --- a/docs/user_related_apis_versioned/1.0.0/users-controller-edit-profile.api.mdx +++ b/docs/user_related_apis_versioned/1.0.0/users-controller-edit-profile.api.mdx @@ -5,7 +5,7 @@ description: "Partially update the authenticated user settings and preferences l sidebar_label: "Edit user profile" hide_title: true hide_table_of_contents: true -api: {"operationId":"UsersController_editProfile","description":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","parameters":[],"requestBody":{"required":true,"description":"Settings fields to update - only include fields you want to change","content":{"application/json":{"schema":{"type":"object","properties":{"languageId":{"type":"number"},"reflectionLanguages":{"type":"array","items":{"type":"string"}},"ayahLanguages":{"type":"array","items":{"type":"string"}},"customized":{"type":"boolean"}},"title":"EditProfileDto"}}}},"responses":{"200":{"description":"Settings updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid settings data"},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/users/profile","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"languageId":0,"reflectionLanguages":["string"],"ayahLanguages":["string"],"customized":true},"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 ## 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"},"postman":{"name":"Edit user profile","description":{"content":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","type":"text/plain"},"url":{"path":["v1","users","profile"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"UsersController_editProfile","description":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","parameters":[],"requestBody":{"required":true,"description":"Settings fields to update - only include fields you want to change","content":{"application/json":{"schema":{"type":"object","properties":{"languageId":{"type":"number"},"reflectionLanguages":{"type":"array","items":{"type":"string"}},"ayahLanguages":{"type":"array","items":{"type":"string"}},"customized":{"type":"boolean"},"hideFollowSuggestion":{"type":"boolean","description":"Hide follow suggestion popup after liking a post"}},"title":"EditProfileDto"}}}},"responses":{"200":{"description":"Settings updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid settings data"},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/users/profile","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"languageId":0,"reflectionLanguages":["string"],"ayahLanguages":["string"],"customized":true,"hideFollowSuggestion":true},"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 ## 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"},"postman":{"name":"Edit user profile","description":{"content":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","type":"text/plain"},"url":{"path":["v1","users","profile"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/1.0.0/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Partially update the authenticated user settings and preferences like notificati Settings fields to update - only include fields you want to change -
        +
      Settings updated successfully diff --git a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx index 0350433d..772dfe13 100644 --- a/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-collection-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark to an existing collection." sidebar_label: "Add collection Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmkwbc0lu0008b0s0ax83876g"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark to an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be added.","example":"cmllufwb7000842jqdmx1fglm"},"required":true,"description":"The Id of the collection to be added."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"}]}}}},"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add collection Bookmark","description":{"content":"Add a bookmark to an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be added.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark to an existing collection. -
      Path Parameters
      Query Parameters
      Request Body
        anyOf
      +
      Path Parameters
      Query Parameters
      Request Body
        anyOf
      Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/add-collection.api.mdx b/docs/user_related_apis_versioned/add-collection.api.mdx index 2b1ae662..5fd34d81 100644 --- a/docs/user_related_apis_versioned/add-collection.api.mdx +++ b/docs/user_related_apis_versioned/add-collection.api.mdx @@ -5,7 +5,7 @@ description: "Create a new collection under user's account." sidebar_label: "Add collection" hide_title: true hide_table_of_contents: true -api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a new collection under user's account.","tags":["Collections"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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"}},"required":["name"],"additionalProperties":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":{"id":{"type":"string","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"name":"Woman in Quran"},"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 ## 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"},"postman":{"name":"Add collection","description":{"content":"Create a new collection under user's account.","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/add-or-update-preference.api.mdx b/docs/user_related_apis_versioned/add-or-update-preference.api.mdx index 1015ab51..3f80492f 100644 --- a/docs/user_related_apis_versioned/add-or-update-preference.api.mdx +++ b/docs/user_related_apis_versioned/add-or-update-preference.api.mdx @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one user preferences group like favorite Tafsirs or translations. -
    Query Parameters
    Request Body
      anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
    +
    Query Parameters
    Request Body
      anyOf= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx index d6adce6d..f3dd3bd4 100644 --- a/docs/user_related_apis_versioned/add-user-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/add-user-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Add a bookmark by details." sidebar_label: "Add user bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add a bookmark by details.","tags":["Bookmarks"],"parameters":[{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["key","type","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","type","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or page"}]}}}},"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","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":false}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"post","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"isReading":true,"mushaf":4},"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 ## 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"},"postman":{"name":"Add user bookmark","description":{"content":"Add a bookmark by details.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add a bookmark by details. -
    Query Parameters
    Request Body
      anyOf
    +
    Query Parameters
    Request Body
      anyOf
    Request has been handled successfully. @@ -34,7 +34,7 @@ Request has been handled successfully. 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
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx b/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx index 99f36e98..bf30f345 100644 --- a/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx +++ b/docs/user_related_apis_versioned/bulk-add-or-update-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Add or update one or more user preferences groups like favorite Ta sidebar_label: "Bulk add or update preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"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,"quranFont":"code_v1","mushafLines":"16_lines"},"translations":{"selectedTranslations":[131]},"tafsirs":{"selectedTafsirs":["en-tafisr-ibn-kathir"]},"audio":{"reciter":7,"playbackRate":1,"showTooltipWhenPlayingAudio":true,"enableAutoScrolling":true},"language":{"language":"en"},"userHasCustomised":{"userHasCustomised":false}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","tags":["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":{"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},"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"],"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,"title":"Preference"}}}},"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}}}},"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}}}}},"method":"post","path":"/v1/preferences/bulk","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"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,"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}},"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 ## 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"},"postman":{"name":"Bulk add or update preferences","description":{"content":"Add or update one or more user preferences groups like favorite Tafsirs and translations.","type":"text/plain"},"url":{"path":["v1","preferences","bulk"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Add or update one or more user preferences groups like favorite Tafsirs and translations. -
    Query Parameters
    Request Body
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    +
    Query Parameters
    Request Body
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/comments-controller-create.api.mdx b/docs/user_related_apis_versioned/comments-controller-create.api.mdx index 885275ce..a563c931 100644 --- a/docs/user_related_apis_versioned/comments-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-create.api.mdx @@ -38,7 +38,7 @@ User mentions in the comment Comment created -
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Invalid comment - empty body or invalid postId diff --git a/docs/user_related_apis_versioned/comments-controller-get.api.mdx b/docs/user_related_apis_versioned/comments-controller-get.api.mdx index b6cda2b6..da4bab67 100644 --- a/docs/user_related_apis_versioned/comments-controller-get.api.mdx +++ b/docs/user_related_apis_versioned/comments-controller-get.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated replies (nested comments) for a parent comment with author in Comment replies with pagination -
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    +
    Schema
      replies object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
      • comment object required
      author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    Parent comment not found diff --git a/docs/user_related_apis_versioned/create-a-goal.api.mdx b/docs/user_related_apis_versioned/create-a-goal.api.mdx index 366a3184..bfb52ec5 100644 --- a/docs/user_related_apis_versioned/create-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/create-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Create a goal" sidebar_label: "Create a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Create a goal","tags":["Goals"],"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:10","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}}}},"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":"cmkwbc0oi000fb0s04c737onv"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Create a goal","tags":["Goals"],"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:10","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}}}},"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":"cmllufwdv000f42jqe7ukd4my"}},"required":["id"],"additionalProperties":false}},"additionalProperties":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}}}}},"method":"post","path":"/v1/goals","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Create a goal","description":{"content":"Create a goal","type":"text/plain"},"url":{"path":["v1","goals"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -42,7 +42,7 @@ The amount of the goal. Depending on the goal type, the amount value and format Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/delete-a-goal.api.mdx b/docs/user_related_apis_versioned/delete-a-goal.api.mdx index 116f4082..da221de5 100644 --- a/docs/user_related_apis_versioned/delete-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/delete-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Delete a goal by id." sidebar_label: "Delete a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a goal by id.","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmllufwdv000f42jqe7ukd4my"},"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}}}},"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}}}}},"method":"delete","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete a goal","description":{"content":"Delete a goal by id.","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The category of the goal","type":"text/plain"},"key":"category","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a goal by id. -
    Path Parameters
    Query Parameters
    Header Parameters
    +
    Path Parameters
    Query Parameters
    Header Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-bookmark.api.mdx b/docs/user_related_apis_versioned/delete-bookmark.api.mdx index 82af9b64..5d644869 100644 --- a/docs/user_related_apis_versioned/delete-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/delete-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark by id." sidebar_label: "Delete Bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmkwbc0j40006b0s0gh8bh75y"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark by id.","tags":["Bookmarks"],"parameters":[{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The id of the bookmark to be deleted.","example":"cmllufw83000642jqazgfho39"},"required":true,"description":"The id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete Bookmark","description":{"content":"Delete a bookmark by id.","type":"text/plain"},"url":{"path":["v1","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark by id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx b/docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx index eb2ca6d2..d82c9f8c 100644 --- a/docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection-bookmark-by-details.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's detail sidebar_label: "Delete collection bookmark by details" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mo000bb0s0agvl9c6c"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}}},"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":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"},{"type":"object","required":["bookmarkId"],"additionalProperties":false,"title":"Bookmark ID"}],"title":"input"}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Delete collection bookmark by details","description":{"content":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"DELETE","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmllufwbz000b42jq1a29a6fn"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}}},"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":{"anyOf":[{"type":"object","required":["key","verseNumber","mushaf"],"additionalProperties":false,"title":"Ayah"},{"type":"object","required":["key","mushaf"],"additionalProperties":false,"title":"Surah, Juz, Or Page"},{"type":"object","required":["bookmarkId"],"additionalProperties":false,"title":"Bookmark ID"}],"title":"input"}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"key":2,"type":"ayah","verseNumber":3,"mushaf":4},"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 ## 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"},"postman":{"name":"Delete collection bookmark by details","description":{"content":"Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"DELETE","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's details. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    +
    Path Parameters
    Query Parameters
    Request Body
      anyOf
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx index 3be0daeb..03563280 100644 --- a/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection-bookmark-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Delete a bookmark from an existing collection by bookmark's id. Wh sidebar_label: "Delete collection bookmark by id" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0mu000cb0s0cm6n09p7"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmkwbc0mu000db0s005p84503"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmllufwc7000c42jqgppy4l7i"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"path","name":"bookmarkId","schema":{"type":"string","description":"The Id of the bookmark to be deleted.","example":"cmllufwc7000d42jqcssd1xyn"},"required":true,"description":"The Id of the bookmark to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}/bookmarks/{bookmarkId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection bookmark by id","description":{"content":"Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId","bookmarks",":bookmarkId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"},{"disabled":false,"description":{"content":"(Required) The Id of the bookmark to be deleted.","type":"text/plain"},"type":"any","value":"","key":"bookmarkId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a bookmark from an existing collection by bookmark's id. When successfully deleted, the bookmark itself does not get deleted but rather only detached from the collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/delete-collection.api.mdx b/docs/user_related_apis_versioned/delete-collection.api.mdx index 7e95d9a0..e1f05cd9 100644 --- a/docs/user_related_apis_versioned/delete-collection.api.mdx +++ b/docs/user_related_apis_versioned/delete-collection.api.mdx @@ -5,7 +5,7 @@ description: "Delete a an existing collection." sidebar_label: "Delete collection" hide_title: true hide_table_of_contents: true -api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmkwbc0m10009b0s0d05fapzk"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} +api: {"description":"Delete a an existing collection.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","description":"The Id of the collection to be deleted.","example":"cmllufwbe000942jq2gbqaan5"},"required":true,"description":"The Id of the collection to be deleted."},{"in":"query","name":"lastMutationAt","schema":{"type":"number","format":"float","description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","example":1731636500303},"required":true,"description":"The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control."}],"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}}},"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}}}},"409":{"description":"Out of Sync Error. The client lastMutationAt does not match server state. Client must re-sync data before retrying this operation.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":false},"error":{"type":"object","properties":{"code":{"type":"string","example":"OutOfSyncError"},"message":{"type":"string","example":"Invalid lastMutationAt, please re-sync your data and try again."}}}}},"examples":{"Out of sync":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"Invalid lastMutationAt, please re-sync your data and try again."}}},"First sync - wrong lastMutationAt":{"value":{"success":false,"error":{"code":"OutOfSyncError","message":"First sync detected. Please use lastMutationAt=-1 for initial sync."}}}}}}},"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}}}}},"method":"delete","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Delete collection","description":{"content":"Delete a an existing collection.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The timestamp of the last mutation that was applied on the server. Required for any data modification operation to ensure concurrency control.","type":"text/plain"},"key":"lastMutationAt","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The Id of the collection to be deleted.","type":"text/plain"},"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"DELETE"}} sidebar_class_name: "delete api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Delete a an existing collection. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. diff --git a/docs/user_related_apis_versioned/get-activity-days.api.mdx b/docs/user_related_apis_versioned/get-activity-days.api.mdx index 9cd112d6..c851833d 100644 --- a/docs/user_related_apis_versioned/get-activity-days.api.mdx +++ b/docs/user_related_apis_versioned/get-activity-days.api.mdx @@ -5,7 +5,7 @@ description: "Get user activity days." sidebar_label: "Get activity days" hide_title: true hide_table_of_contents: true -api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user activity days.","tags":["Activity Days"],"parameters":[{"in":"query","name":"from","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The start date of the activity days","example":"2023-09-01"},"description":"The start date of the activity days"},{"in":"query","name":"to","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The last date of the activity days","example":"2023-09-31"},"description":"The last date of the activity days"},{"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 type of the activity day","example":"QURAN"},"description":"The type of the activity day"},{"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":"cmllufw2m000442jqb9o141br"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/activity-days","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get activity days","description":{"content":"Get user activity days.","type":"text/plain"},"url":{"path":["v1","activity-days"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The start date of the activity days","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The last date of the activity days","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"Order by activity day's date","type":"text/plain"},"key":"dateOrderBy","value":""},{"disabled":false,"description":{"content":"The type of the activity day","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user activity days. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
      • ranges object
      +
      Schema
        data object[]
      • Array [
        • ranges object
        The ranges read on that day (will be included only when the type is QURAN) @@ -102,7 +102,7 @@ The remaining range of Ayahs user should read on that day to meet their goal's t 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) -
      • ]
        • pagination object
      +
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx index 80738542..41c99d34 100644 --- a/docs/user_related_apis_versioned/get-all-collection-items.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collection-items.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing collections along with resources that belong to t sidebar_label: "Get all collection items" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing collections along with resources that belong to them.","tags":["Collections"],"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/all","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collection items","description":{"content":"Get all existing collections along with resources that belong to them.","type":"text/plain"},"url":{"path":["v1","collections","all"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing collections along with resources that belong to them. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-collections.api.mdx b/docs/user_related_apis_versioned/get-all-collections.api.mdx index 93cc120e..0a432f72 100644 --- a/docs/user_related_apis_versioned/get-all-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-all-collections.api.mdx @@ -5,7 +5,7 @@ description: "List collections owned by the user. This api contains pagination. sidebar_label: "Get all collections" hide_title: true hide_table_of_contents: true -api: {"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)","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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"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)","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":"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all collections","description":{"content":"List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination)","type":"text/plain"},"url":{"path":["v1","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collections list either by the time they were updated at descendingly or alphabetically.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; List collections owned by the user. This api contains pagination. Read more about [pagination](/docs/user_related_apis_versioned/user-related-apis#pagination) -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-all-notes.api.mdx b/docs/user_related_apis_versioned/get-all-notes.api.mdx index 6ce79e3e..e38f86cf 100644 --- a/docs/user_related_apis_versioned/get-all-notes.api.mdx +++ b/docs/user_related_apis_versioned/get-all-notes.api.mdx @@ -5,7 +5,7 @@ description: "List notes owned by the user. This API contains pagination. Read m sidebar_label: "Get all notes" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"tags":["Notes"],"description":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","parameters":[{"in":"query","name":"cursor","schema":{"type":"string","description":"A cursor for pagination, used to fetch the next set of results.","example":"cursor123"},"description":"A cursor for pagination, used to fetch the next set of results."},{"in":"query","name":"limit","schema":{"type":"number","format":"float","minimum":1,"maximum":50,"description":"The maximum number of notes to return, defaults to 20.","example":20,"default":20},"description":"The maximum number of notes to return, defaults to 20."},{"in":"query","name":"sortBy","schema":{"type":"string","enum":["newest","oldest"],"description":"The sorting order of the notes, defaults to newest first.","example":"newest","default":"newest"},"description":"The sorting order of the notes, defaults to newest first."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get all notes","description":{"content":"List notes owned by the user. This API contains pagination. Read more about [pagination](/#pagination)","type":"text/plain"},"url":{"path":["v1","notes"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"A cursor for pagination, used to fetch the next set of results.","type":"text/plain"},"key":"cursor","value":""},{"disabled":false,"description":{"content":"The maximum number of notes to return, defaults to 20.","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"The sorting order of the notes, defaults to newest first.","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx index 18a3721f..2344ca59 100644 --- a/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark-collections.api.mdx @@ -5,7 +5,7 @@ description: "Get all collections that a bookmark belongs to by bookmark details sidebar_label: "Get bookmark collections" hide_title: true hide_table_of_contents: true -api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all collections that a bookmark belongs to by bookmark details.","tags":["Bookmarks"],"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":"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":"object","properties":{"id":{"type":"string","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"}}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/collections","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark collections","description":{"content":"Get all collections that a bookmark belongs to by bookmark details.","type":"text/plain"},"url":{"path":["v1","bookmarks","collections"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all collections that a bookmark belongs to by bookmark details. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
    +
    Schema
      data object[]
    • Array [
    • ]
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmark.api.mdx b/docs/user_related_apis_versioned/get-bookmark.api.mdx index 049edc2e..355da5ca 100644 --- a/docs/user_related_apis_versioned/get-bookmark.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmark.api.mdx @@ -5,7 +5,7 @@ description: "Get a bookmark by details" sidebar_label: "Get bookmark" hide_title: true hide_table_of_contents: true -api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"key","schema":{"type":"integer","description":"Surah, Juz or page number.","example":2},"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":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"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","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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get a bookmark by details","tags":["Bookmarks"],"parameters":[{"in":"query","name":"verseNumber","schema":{"type":"integer","description":"The Ayah number of the bookmark"},"required":false,"description":"The Ayah number of the bookmark"},{"in":"query","name":"isReading","schema":{"type":"boolean","description":"Whether to fetch the reading bookmark"},"required":false,"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},"required":false,"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"},"required":false,"description":"The bookmark type."},{"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","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":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/bookmark","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmark","description":{"content":"Get a bookmark by details","type":"text/plain"},"url":{"path":["v1","bookmarks","bookmark"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The Ayah number of the bookmark","type":"text/plain"},"key":"verseNumber","value":""},{"disabled":false,"description":{"content":"Whether to fetch the reading bookmark","type":"text/plain"},"key":"isReading","value":""},{"disabled":false,"description":{"content":"Surah, Juz or page number.","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushaf","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get a bookmark by details -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
    +
    Schema
      data object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx index bd9ef8e5..7da89c7c 100644 --- a/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx +++ b/docs/user_related_apis_versioned/get-bookmarks-within-a-range-of-ayahs.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks within a specific Ayahs range." sidebar_label: "Get bookmarks within a range of Ayahs" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks within a specific Ayahs range.","tags":["Bookmarks"],"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":{"type":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks/ayahs-range","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get bookmarks within a range of Ayahs","description":{"content":"Get all bookmarks within a specific Ayahs range.","type":"text/plain"},"url":{"path":["v1","bookmarks","ayahs-range"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The number of the Surah that the Ayahs range belong to.","type":"text/plain"},"key":"chapterNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range starts.","type":"text/plain"},"key":"rangeStartAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) The Ayah number at which the range ends.","type":"text/plain"},"key":"rangeEndAyahNumber","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all bookmarks within a specific Ayahs range. Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx index 7d07be1c..e8eb0536 100644 --- a/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx +++ b/docs/user_related_apis_versioned/get-collection-items-by-id.api.mdx @@ -5,7 +5,7 @@ description: "Get all resources that belong to an existing collection by collect sidebar_label: "Get collection items by id" hide_title: true hide_table_of_contents: true -api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmkwbc0ng000eb0s04gn2b009"}},{"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0k10007b0s0g5jh3l4e"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all resources that belong to an existing collection by collection id.","tags":["Collections"],"parameters":[{"in":"path","name":"collectionId","schema":{"type":"string","example":"cmllufwcx000e42jqbbko1239"}},{"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":{"type":"object","properties":{"id":{"type":"string","example":"cmllufw99000742jq5vr5997v"},"updatedAt":{"type":"string","format":"date-time","example":"2023-01-21T07:28:13.023Z"},"name":{"type":"string","example":"Woman in Quran"}},"required":["id","updatedAt","name"],"additionalProperties":false,"title":"Collection"},"bookmarks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}}},"additionalProperties":false},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/collections/{collectionId}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get collection items by id","description":{"content":"Get all resources that belong to an existing collection by collection id.","type":"text/plain"},"url":{"path":["v1","collections",":collectionId"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Sort the collection items either by the time they were added at descendingly or by Ayah key.","type":"text/plain"},"key":"sortBy","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[{"disabled":false,"type":"any","value":"","key":"collectionId"}]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all resources that belong to an existing collection by collection id. -
    Path Parameters
    Query Parameters
    +
    Path Parameters
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object
      collection object
      bookmarks object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx index cc11005c..56533386 100644 --- a/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/get-notes-by-verse.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve notes by a specific verse." sidebar_label: "Get notes by verse" hide_title: true hide_table_of_contents: true -api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} +api: {"tags":["Notes"],"description":"Retrieve notes by a specific verse.","parameters":[{"in":"query","name":"verseKey","schema":{"type":"string","pattern":"^(\\d+):(\\d+)$","description":"The verse key for which notes are being requested.","example":"2:255"},"required":true,"description":"The verse key for which notes are being requested."}],"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 unique identifier of the note.","example":"asdasdqwe1231"},"createdAt":{"type":"string","format":"date-time","description":"The creation date of the note.","example":"2023-01-21T07:28:13.023Z"},"updatedAt":{"type":"string","format":"date-time","description":"The last update date of the note.","example":"2023-01-22T07:28:13.023Z"},"body":{"type":"string","minLength":6,"maxLength":10000,"description":"The main content of the note, must be between the specified minimum and maximum length.","example":"This is a sample note body."},"source":{"type":"string","description":"The source of the note.","example":"we23412312weq"},"attachedEntities":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string","description":"The unique identifier for the attached entity.","example":"entity123"},"entityType":{"type":"string","enum":["reflection"],"description":"The type of the attached entity, must be one of the predefined NoteEntityType values.","example":"reflection"},"entityMetadata":{"type":"object","properties":{},"description":"Additional metadata for the attached entity.","example":{"key":"value"}}},"required":["entityId","entityType"],"additionalProperties":false},"description":"An array of attached entities associated with the note."},"ranges":{"type":"array","items":{"type":"string","pattern":"^(\\d+):(\\d+)-(\\d+):(\\d+)$"},"description":"An array of verse ranges associated with the note.","example":["2:255-2:257"]}},"required":["id","createdAt","updatedAt","body"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/notes/by-verse/:verseKey","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -38,7 +38,7 @@ An array of attached entities associated with the note. Additional metadata for the attached entity. -
  • ]
  • ]
    • pagination object
    +
  • ]
  • ]
    • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-streaks.api.mdx b/docs/user_related_apis_versioned/get-streaks.api.mdx index 8a773140..d261243a 100644 --- a/docs/user_related_apis_versioned/get-streaks.api.mdx +++ b/docs/user_related_apis_versioned/get-streaks.api.mdx @@ -5,7 +5,7 @@ description: "Get user streaks." sidebar_label: "Get streaks" hide_title: true hide_table_of_contents: true -api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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 streak.","example":"cmkwbc0zd000hb0s04j4j2nuj"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get user streaks.","tags":["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-31"},"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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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 streak.","example":"cmllufwnz000h42jq9fhh3626"},"startDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-01"},"endDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the streak.","example":"2023-09-31"},"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","status","days"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/streaks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get streaks","description":{"content":"Get user streaks.","type":"text/plain"},"url":{"path":["v1","streaks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The date after which any streaks would be returned (inclusive)","type":"text/plain"},"key":"from","value":""},{"disabled":false,"description":{"content":"The date before which any streaks would be returned (inclusive)","type":"text/plain"},"key":"to","value":""},{"disabled":false,"description":{"content":"The type of the streak","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"The sorting order of `orderBy` field","type":"text/plain"},"key":"sortOrder","value":""},{"disabled":false,"description":{"content":"Which field to order the streaks by","type":"text/plain"},"key":"orderBy","value":""},{"disabled":false,"description":{"content":"The status of the streak.","type":"text/plain"},"key":"status","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get user streaks. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx index c3099cc0..860f0df2 100644 --- a/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx +++ b/docs/user_related_apis_versioned/get-todays-goal-plan.api.mdx @@ -5,7 +5,7 @@ description: "Get today's goal plan." sidebar_label: "Get today's goal plan" hide_title: true hide_table_of_contents: true -api: {"description":"Get today's goal plan.","tags":["Goals"],"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":"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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmkwbc0ec0004b0s040lfctn8"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get today's goal plan.","tags":["Goals"],"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":"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":{"hasGoal":{"type":"boolean","description":"User has a goal.","example":false}},"required":["hasGoal"],"additionalProperties":false,"oneOf":[{"type":"object","properties":{"id":{"type":"string","description":"The id of the activity day.","example":"cmllufw2m000442jqb9o141br"},"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The date of the activity day.","example":"2023-09-31"},"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 type of the activity day","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","title":"When user has a goal"}]}},"additionalProperties":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}}}}},"method":"get","path":"/v1/goals/get-todays-plan","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get today's goal plan","description":{"content":"Get today's goal plan.","type":"text/plain"},"url":{"path":["v1","goals","get-todays-plan"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) The type of the goal.","type":"text/plain"},"key":"type","value":""}],"variable":[]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get today's goal plan. Request has been handled successfully. -
    Schema
      data object
      oneOf

      object

    +
    Schema
      data object
      oneOf

      object

    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx index 608899ee..d57d7ee6 100644 --- a/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx +++ b/docs/user_related_apis_versioned/get-user-bookmarks.api.mdx @@ -5,7 +5,7 @@ description: "Get all bookmarks. This includes bookmarks belonging to a collecti sidebar_label: "Get user bookmarks" hide_title: true hide_table_of_contents: true -api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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":"object","properties":{"id":{"type":"string","example":"cmkwbc0iu0005b0s028eh6ztm"},"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","example":5},"group":{"type":"string"}},"required":["id","createdAt","type","key"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all bookmarks. This includes bookmarks belonging to a collection.","tags":["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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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":"object","properties":{"id":{"type":"string","example":"cmllufw7u000542jq4x0jhz4u"},"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","example":5},"group":{"type":"string"},"isInDefaultCollection":{"type":"boolean","example":true}},"required":["id","createdAt","type","key","isInDefaultCollection"],"additionalProperties":false,"title":"Bookmark"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/bookmarks","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user bookmarks","description":{"content":"Get all bookmarks. This includes bookmarks belonging to a collection.","type":"text/plain"},"url":{"path":["v1","bookmarks"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The bookmark type.","type":"text/plain"},"key":"type","value":""},{"disabled":false,"description":{"content":"Whether to fetch only the reading bookmark","type":"text/plain"},"key":"isReading","value":""},{"disabled":false,"description":{"content":"Filter by key (surah/juz/page number)","type":"text/plain"},"key":"key","value":""},{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all bookmarks. This includes bookmarks belonging to a collection. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-preferences.api.mdx b/docs/user_related_apis_versioned/get-user-preferences.api.mdx index 1893c3b0..e27093a3 100644 --- a/docs/user_related_apis_versioned/get-user-preferences.api.mdx +++ b/docs/user_related_apis_versioned/get-user-preferences.api.mdx @@ -5,7 +5,7 @@ description: "Get all user preferences like theme, favorite reciter, default lan sidebar_label: "Get user preferences" hide_title: true hide_table_of_contents: true -api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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},"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"}},"required":["tafsirFontScale","quranTextFontScale","translationFontScale","wordByWordFontScale","reflectionFontScale","qnaFontScale","lessonFontScale"],"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,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all user preferences like theme, favorite reciter, default language etc.","tags":["Preferences"],"parameters":[],"responses":{"200":{"description":"Request has been handled successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"data":{"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},"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"],"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,"title":"Preference"}},"additionalProperties":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}}}}},"method":"get","path":"/v1/preferences","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user preferences","description":{"content":"Get all user preferences like theme, favorite reciter, default language etc.","type":"text/plain"},"url":{"path":["v1","preferences"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Get all user preferences like theme, favorite reciter, default language etc. Request has been handled successfully. -
    Schema
      data object
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    +
    Schema
      data object
      theme object
      reading object
      = 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>= 1`"} schema={{"type":"array","items":{"type":"string","maxLength":10},"minItems":1}}>
      quranReaderStyles object
      = 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 6`"} schema={{"type":"integer","minimum":1,"maximum":6,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>= 1` and `<= 10`"} schema={{"type":"integer","minimum":1,"maximum":10,"example":3}}>
      translations object
      tafsirs object
      audio object
      language object
      userHasCustomised object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx index b5a8d1c3..67753f7b 100644 --- a/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx +++ b/docs/user_related_apis_versioned/get-user-reading-sessions.api.mdx @@ -5,7 +5,7 @@ description: "Get all existing reading sessions." sidebar_label: "Get user reading sessions" hide_title: true hide_table_of_contents: true -api: {"description":"Get all existing reading sessions.","tags":["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":"cmkwbc0dr0000b0s0fboz3anv"},"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":"cmkwbc0ds0001b0s01bxvcw79"},"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","example":"cmkwbc0yr000gb0s01wvy1ntj"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmkwbc0ds0002b0s0aeub15nr"},"endCursor":{"type":"string","example":"cmkwbc0ds0003b0s0a2whdvgb"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} +api: {"description":"Get all existing reading sessions.","tags":["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":"cmllufw25000042jqhmcfez63"},"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":"cmllufw25000142jq27mq9zle"},"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","example":"cmllufwnf000g42jq7xsp5ndw"},"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,"title":"ReadingSession"}},"pagination":{"type":"object","properties":{"startCursor":{"type":"string","example":"cmllufw25000242jq7syu6r8q"},"endCursor":{"type":"string","example":"cmllufw26000342jq37j17vvo"},"hasNextPage":{"type":"boolean","example":true},"hasPreviousPage":{"type":"boolean","example":false}},"additionalProperties":false}},"additionalProperties":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}}}}},"method":"get","path":"/v1/reading-sessions","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get user reading sessions","description":{"content":"Get all existing reading sessions.","type":"text/plain"},"url":{"path":["v1","reading-sessions"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"The number of items to be fetched. Should be used together with `before`","type":"text/plain"},"key":"last","value":""},{"disabled":false,"description":{"content":"The number of items to be fetched.","type":"text/plain"},"key":"first","value":""},{"disabled":false,"description":{"content":"The cursor after which you want to get the next page of items. Should be used together with `first`","type":"text/plain"},"key":"after","value":""},{"disabled":false,"description":{"content":"The cursor before which the previous page of items will be fetched. Should be used together with `last`","type":"text/plain"},"key":"before","value":""}],"variable":[]},"header":[{"key":"Accept","value":"application/json"}],"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,11 +26,11 @@ import TabItem from "@theme/TabItem"; Get all existing reading sessions. -
    Query Parameters
    +
    Query Parameters
    Request has been handled successfully. -
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    +
    Schema
      data object[]
    • Array [
    • ]
      • pagination object
    The request is missing required parameters or is invalid. diff --git a/docs/user_related_apis_versioned/posts-controller-create.api.mdx b/docs/user_related_apis_versioned/posts-controller-create.api.mdx index 2cabd1c9..abb46dfe 100644 --- a/docs/user_related_apis_versioned/posts-controller-create.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-create.api.mdx @@ -5,7 +5,7 @@ description: "Create a new post (reflection) with Quran references. Posts can be sidebar_label: "Create post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:24.493Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_create","description":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","parameters":[],"requestBody":{"required":true,"description":"Post creation payload containing the post object with body, references, mentions, and visibility settings","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"required":["roomPostStatus","body","draft","references","mentions","roomId","postAsAuthorId","publishedAt"],"title":"CreatePostDto"}},"required":["post"],"title":"CreatePostBodyDto"}}}},"responses":{"201":{"description":"Post created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"400":{"description":"Invalid post data - body too short, invalid references, or invalid room post status"},"401":{"description":"User not authenticated"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"post","path":"/v1/posts","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"post":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-02-14T04:59:38.379Z"}},"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 ## 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"},"postman":{"name":"Create post","description":{"content":"Create a new post (reflection) with Quran references. Posts can be public, drafts, or associated with a room (group/page). Supports user mentions and multiple Quran verse references. Minimum body length is 6 characters.","type":"text/plain"},"url":{"path":["v1","posts"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"POST","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "post api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Post creation payload containing the post object with body, references, mentions Post created successfully -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Invalid post data - body too short, invalid references, or invalid room post status diff --git a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx index c1a98753..882dbbff 100644 --- a/docs/user_related_apis_versioned/posts-controller-edit.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-edit.api.mdx @@ -5,7 +5,7 @@ description: "Update an existing post. Only the post author or admins can edit. sidebar_label: "Edit post" hide_title: true hide_table_of_contents: true -api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-01-27T08:09:24.493Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"PostsController_edit","description":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","parameters":[{"name":"id","required":true,"in":"path","description":"Unique numeric post ID to update","schema":{"type":"number"}}],"requestBody":{"required":true,"description":"Partial post data to update - only include fields to change","content":{"application/json":{"schema":{"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":{"type":"object","properties":{"chapterId":{"type":"number","minimum":1},"from":{"type":"number","default":0},"to":{"type":"number","default":0}},"required":["chapterId","from","to"],"title":"ReferenceAttributes"}},"mentions":{"type":"array","items":{"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"],"title":"UserMentionAttributes"}},"roomId":{"type":"number"},"postAsAuthorId":{"type":"string"},"publishedAt":{"format":"date-time","type":"string"}},"title":"UpdatePostDto"}}}},"responses":{"200":{"description":"Post updated successfully with the updated post data","content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"language":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"}},"required":["id"],"title":"PostTag"}},"references":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"from":{"type":"number"},"to":{"type":"number"},"chapterId":{"type":"number"}},"required":["id"],"title":"PostReference"}},"author":{"type":"object"},"recentComment":{"type":"object","properties":{"id":{"type":"number"},"author":{"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"],"title":"UserAuthor"},"body":{"type":"string"},"createdAt":{"format":"date-time","type":"string"}},"required":["id","author","body","createdAt"],"title":"PostRecentComment"},"room":{"nullable":true,"allOf":[{"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"],"title":"PostRoom"}]},"mentions":{"type":"array","items":{"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"],"title":"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"},"estimatedReadingTime":{"type":"number","default":0},"roomId":{"type":"number"},"postTypeId":{"type":"number"},"postTypeName":{"type":"string"}},"required":["id","authorId","createdAt","updatedAt","commentsCount","roomId","postTypeId"],"title":"PostSerialized"},"success":{"type":"boolean"}},"required":["post","success"],"title":"PostCreatedResponse"}}}},"401":{"description":"User not authenticated"},"403":{"description":"User not authorized to edit this post"},"404":{"description":"Post not found"}},"tags":["Posts"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/posts/{id}","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"roomPostStatus":0,"body":"string","draft":true,"references":[{"chapterId":0,"from":0,"to":0}],"mentions":[{"marker":"{{9e639c0f-e02f-c32f-b0ae-e0d8c8d80b2d}}","userId":"string","displayName":"string"}],"roomId":0,"postAsAuthorId":"string","publishedAt":"2026-02-14T04:59:38.379Z"},"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 ## 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"},"postman":{"name":"Edit post","description":{"content":"Update an existing post. Only the post author or admins can edit. Supports updating body, references, mentions, draft status, and room visibility settings.","type":"text/plain"},"url":{"path":["v1","posts",":id"],"host":["{{baseUrl}}"],"query":[],"variable":[{"disabled":false,"description":{"content":"(Required) Unique numeric post ID to update","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -34,7 +34,7 @@ Partial post data to update - only include fields to change Post updated successfully with the updated post data -
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      post object required
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx index 526f6110..8f49a266 100644 --- a/docs/user_related_apis_versioned/posts-controller-feed.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-feed.api.mdx @@ -30,5 +30,5 @@ Retrieve a paginated feed of posts (reflections). Supports filtering by authors, Feed retrieved successfully with paginated posts -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx index 0d9c9d2e..a891141c 100644 --- a/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-find-one.api.mdx @@ -30,7 +30,7 @@ Retrieve a specific post by its unique numeric ID. Returns the full post with au Post found and returned with all associated data -
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    +
    Schema
      tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    Post not found or has been deleted diff --git a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx index 18d8d089..39f6493c 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-all-comment.api.mdx @@ -30,7 +30,7 @@ Retrieve all comments for a post in a single request without pagination. Useful All comments returned with total count -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx index 7822fc33..ce8b2823 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-comments.api.mdx @@ -30,7 +30,7 @@ Retrieve paginated top-level comments for a post. Use the replies endpoint to ge Comments retrieved with pagination metadata -
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    +
    Schema
      comments object[] required
    • Array [
      • author object
      avatarUrls object required
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
      • tags object[]
    • Array [
    • ]
    • ]
    Post not found diff --git a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx index 64033c4d..b2747403 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-loggedin-user-posts.api.mdx @@ -30,7 +30,7 @@ Retrieve posts created by the currently authenticated user. Supports filtering b User posts retrieved successfully with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    User not authenticated diff --git a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx index 11611200..edf67e5c 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-my-posts-by-verse.api.mdx @@ -30,7 +30,7 @@ Retrieve all posts written by the current user for a specific Quran verse. Retur User posts for the specified verse -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    Invalid verse key format diff --git a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx index d73df9ab..53860d2d 100644 --- a/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx +++ b/docs/user_related_apis_versioned/posts-controller-get-user-post.api.mdx @@ -30,5 +30,5 @@ Retrieve public posts created by a specific user. If viewing own posts while aut User posts retrieved with pagination metadata -
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    +
    Schema
      data object[] required
    • Array [
      • tags object[]
    • Array [
    • ]
      • references object[]
    • Array [
    • ]
      • recentComment object
      author object required
      avatarUrls object required
      room object nullable
      mentions object[]
    • Array [
      • avatarUrls object required
    • ]
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/rooms-controller-get-rooms.api.mdx b/docs/user_related_apis_versioned/rooms-controller-get-rooms.api.mdx index 209387ec..14f0b694 100644 --- a/docs/user_related_apis_versioned/rooms-controller-get-rooms.api.mdx +++ b/docs/user_related_apis_versioned/rooms-controller-get-rooms.api.mdx @@ -5,7 +5,7 @@ description: "Retrieve rooms the user has joined (joined-rooms) or manages as ad sidebar_label: "Get joined or managed rooms" hide_title: true hide_table_of_contents: true -api: {"operationId":"RoomsController_getRooms","description":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","parameters":[{"name":"query","required":false,"in":"query","description":"Search query for room names","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Rooms per page (default: 5)","schema":{"minimum":1,"maximum":5,"default":5,"type":"number"}}],"responses":{"200":{"description":"Rooms retrieved with pagination"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"get","path":"/v1/rooms/joined-rooms","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get joined or managed rooms","description":{"content":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","type":"text/plain"},"url":{"path":["v1","rooms","joined-rooms"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Search query for room names","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Page number (default: 1)","type":"text/plain"},"key":"page","value":""},{"disabled":false,"description":{"content":"Rooms per page (default: 5)","type":"text/plain"},"key":"limit","value":""}],"variable":[]},"method":"GET"}} +api: {"operationId":"RoomsController_getRooms","description":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","parameters":[{"name":"query","required":false,"in":"query","description":"Search query for room names","schema":{"type":"string"}},{"name":"page","required":false,"in":"query","description":"Page number (default: 1)","schema":{"minimum":1,"default":1,"type":"number"}},{"name":"limit","required":false,"in":"query","description":"Rooms per page (default: 5)","schema":{"minimum":1,"maximum":5,"default":5,"type":"number"}},{"name":"sortBy","required":false,"in":"query","description":"Sort order (default: NAME_ASC)","schema":{"enum":["NAME_ASC","NAME_DESC","LATEST_ACTIVITY"],"type":"string"}}],"responses":{"200":{"description":"Rooms retrieved with pagination"},"401":{"description":"User not authenticated"}},"tags":["Rooms"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"get","path":"/v1/rooms/joined-rooms","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"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 ## 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"},"postman":{"name":"Get joined or managed rooms","description":{"content":"Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination.","type":"text/plain"},"url":{"path":["v1","rooms","joined-rooms"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"Search query for room names","type":"text/plain"},"key":"query","value":""},{"disabled":false,"description":{"content":"Page number (default: 1)","type":"text/plain"},"key":"page","value":""},{"disabled":false,"description":{"content":"Rooms per page (default: 5)","type":"text/plain"},"key":"limit","value":""},{"disabled":false,"description":{"content":"Sort order (default: NAME_ASC)","type":"text/plain"},"key":"sortBy","value":""}],"variable":[]},"method":"GET"}} sidebar_class_name: "get api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Retrieve rooms the user has joined (joined-rooms) or manages as admin (managed-rooms). Supports search and pagination. -
    Query Parameters
    +
    Query Parameters
    Rooms retrieved with pagination diff --git a/docs/user_related_apis_versioned/tags-controller-find.api.mdx b/docs/user_related_apis_versioned/tags-controller-find.api.mdx index b38c2759..ba2ec66a 100644 --- a/docs/user_related_apis_versioned/tags-controller-find.api.mdx +++ b/docs/user_related_apis_versioned/tags-controller-find.api.mdx @@ -30,5 +30,5 @@ Search for tags by query string. Returns paginated results matching the search t Tags matching search query with pagination -
    Schema
    • Array [
    • ]
    +
    Schema
    • Array [
    • ]
    \ No newline at end of file diff --git a/docs/user_related_apis_versioned/update-a-goal.api.mdx b/docs/user_related_apis_versioned/update-a-goal.api.mdx index 09ef7bfa..3778d7cd 100644 --- a/docs/user_related_apis_versioned/update-a-goal.api.mdx +++ b/docs/user_related_apis_versioned/update-a-goal.api.mdx @@ -5,7 +5,7 @@ description: "Update a goal" sidebar_label: "Update a goal" hide_title: true hide_table_of_contents: true -api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmkwbc0oi000fb0s04c737onv"},"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:10","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}}}},"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}}}},"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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"description":"Update a goal","tags":["Goals"],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"The id of the goal.","example":"cmllufwdv000f42jqe7ukd4my"},"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:10","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}}}},"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}}}},"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}}}}},"method":"put","path":"/v1/goals/{id}","servers":[{"url":"https://apis-prelive.quran.foundation/auth","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/auth","description":"Production Server"}],"security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"type":"QURAN_TIME","amount":"1:5-1:10","duration":0,"category":"QURAN"},"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 ## 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"},"postman":{"name":"Update a goal","description":{"content":"Update a goal","type":"text/plain"},"url":{"path":["v1","goals",":id"],"host":["{{baseUrl}}"],"query":[{"disabled":false,"description":{"content":"(Required) 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","type":"text/plain"},"key":"mushafId","value":""}],"variable":[{"disabled":false,"description":{"content":"(Required) The id of the goal.","type":"text/plain"},"type":"any","value":"","key":"id"}]},"header":[{"disabled":false,"description":{"content":"The current timezone of the user. Not providing the value might affect the accuracy of how we calculate days and streaks.","type":"text/plain"},"key":"x-timezone","value":""},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PUT","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "put api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -26,7 +26,7 @@ import TabItem from "@theme/TabItem"; Update a goal -
    Path Parameters
    Query Parameters
    Header Parameters
    Request Body
      amount object
      +
      Path Parameters
      Query Parameters
      Header Parameters
      Request Body
        amount object
        The amount of the goal. Depending on the goal type, the amount value and format will be different diff --git a/docs/user_related_apis_versioned/users-controller-edit-profile.api.mdx b/docs/user_related_apis_versioned/users-controller-edit-profile.api.mdx index c075b790..c40e2f60 100644 --- a/docs/user_related_apis_versioned/users-controller-edit-profile.api.mdx +++ b/docs/user_related_apis_versioned/users-controller-edit-profile.api.mdx @@ -5,7 +5,7 @@ description: "Partially update the authenticated user settings and preferences l sidebar_label: "Edit user profile" hide_title: true hide_table_of_contents: true -api: {"operationId":"UsersController_editProfile","description":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","parameters":[],"requestBody":{"required":true,"description":"Settings fields to update - only include fields you want to change","content":{"application/json":{"schema":{"type":"object","properties":{"languageId":{"type":"number"},"reflectionLanguages":{"type":"array","items":{"type":"string"}},"ayahLanguages":{"type":"array","items":{"type":"string"}},"customized":{"type":"boolean"}},"title":"EditProfileDto"}}}},"responses":{"200":{"description":"Settings updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid settings data"},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/users/profile","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"languageId":0,"reflectionLanguages":["string"],"ayahLanguages":["string"],"customized":true},"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 ## 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"},"postman":{"name":"Edit user profile","description":{"content":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","type":"text/plain"},"url":{"path":["v1","users","profile"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} +api: {"operationId":"UsersController_editProfile","description":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","parameters":[],"requestBody":{"required":true,"description":"Settings fields to update - only include fields you want to change","content":{"application/json":{"schema":{"type":"object","properties":{"languageId":{"type":"number"},"reflectionLanguages":{"type":"array","items":{"type":"string"}},"ayahLanguages":{"type":"array","items":{"type":"string"}},"customized":{"type":"boolean"},"hideFollowSuggestion":{"type":"boolean","description":"Hide follow suggestion popup after liking a post"}},"title":"EditProfileDto"}}}},"responses":{"200":{"description":"Settings updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"400":{"description":"Invalid settings data"},"401":{"description":"User not authenticated"}},"tags":["Users"],"servers":[{"url":"https://apis-prelive.quran.foundation/quran-reflect","description":"Pre-production Server"},{"url":"https://apis.quran.foundation/quran-reflect","description":"Production Server"}],"method":"patch","path":"/v1/users/profile","security":[{"x-auth-token":[],"x-client-id":[]}],"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"}},"jsonRequestBodyExample":{"languageId":0,"reflectionLanguages":["string"],"ayahLanguages":["string"],"customized":true,"hideFollowSuggestion":true},"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 ## 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"},"postman":{"name":"Edit user profile","description":{"content":"Partially update the authenticated user settings and preferences like notification settings, privacy options, and display preferences.","type":"text/plain"},"url":{"path":["v1","users","profile"],"host":["{{baseUrl}}"],"query":[],"variable":[]},"header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"method":"PATCH","body":{"mode":"raw","raw":"\"\"","options":{"raw":{"language":"json"}}}}} sidebar_class_name: "patch api-method" info_path: docs/user_related_apis_versioned/user-related-apis custom_edit_url: null @@ -30,7 +30,7 @@ Partially update the authenticated user settings and preferences like notificati Settings fields to update - only include fields you want to change -
        +
      Settings updated successfully diff --git a/openAPI/user-related-apis/v1.json b/openAPI/user-related-apis/v1.json index 3b05833c..0303327a 100644 --- a/openAPI/user-related-apis/v1.json +++ b/openAPI/user-related-apis/v1.json @@ -34,7 +34,7 @@ "Bookmark": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmkwbc0iu0005b0s028eh6ztm" }, + "id": { "type": "string", "example": "cmllufw7u000542jq4x0jhz4u" }, "createdAt": { "type": "string", "format": "date-time", @@ -43,15 +43,16 @@ "type": { "type": "string", "example": "ayah" }, "key": { "type": "integer", "example": 1 }, "verseNumber": { "type": "integer", "example": 5 }, - "group": { "type": "string" } + "group": { "type": "string" }, + "isInDefaultCollection": { "type": "boolean", "example": true } }, - "required": ["id", "createdAt", "type", "key"], + "required": ["id", "createdAt", "type", "key", "isInDefaultCollection"], "additionalProperties": false }, "Collection": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmkwbc0k10007b0s0g5jh3l4e" }, + "id": { "type": "string", "example": "cmllufw99000742jq5vr5997v" }, "updatedAt": { "type": "string", "format": "date-time", @@ -245,6 +246,18 @@ "maximum": 10, "example": 3 }, + "surahInfoFontScale": { + "type": "integer", + "minimum": 1, + "maximum": 10, + "example": 3 + }, + "hadithFontScale": { + "type": "integer", + "minimum": 1, + "maximum": 10, + "example": 3 + }, "quranFont": { "type": "string", "enum": [ @@ -262,7 +275,8 @@ "type": "string", "enum": ["15_lines", "16_lines"], "example": "16_lines" - } + }, + "showTajweedRules": { "type": "boolean", "example": true } }, "required": [ "tafsirFontScale", @@ -271,7 +285,9 @@ "wordByWordFontScale", "reflectionFontScale", "qnaFontScale", - "lessonFontScale" + "lessonFontScale", + "surahInfoFontScale", + "hadithFontScale" ], "additionalProperties": false }, @@ -357,7 +373,7 @@ "ReadingSession": { "type": "object", "properties": { - "id": { "type": "string", "example": "cmkwbc0yr000gb0s01wvy1ntj" }, + "id": { "type": "string", "example": "cmllufwnf000g42jq7xsp5ndw" }, "updatedAt": { "type": "string", "format": "date-time", @@ -397,7 +413,11 @@ "items": { "type": "string" } }, "ayahLanguages": { "type": "array", "items": { "type": "string" } }, - "customized": { "type": "boolean" } + "customized": { "type": "boolean" }, + "hideFollowSuggestion": { + "type": "boolean", + "description": "Hide follow suggestion popup after liking a post" + } } }, "UserSerializedDto": { @@ -1493,7 +1513,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -1504,7 +1524,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -1527,11 +1547,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -1764,7 +1784,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be added.", - "example": "cmkwbc0lu0008b0s0ax83876g" + "example": "cmllufwb7000842jqdmx1fglm" }, "required": true, "description": "The Id of the collection to be added." @@ -2131,7 +2151,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmkwbc0mo000bb0s0agvl9c6c" + "example": "cmllufwbz000b42jq1a29a6fn" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2429,7 +2449,7 @@ "bookmarkId": { "type": "string", "description": "The Id of the bookmark to be deleted.", - "example": "cmkwbc0mo000ab0s0ddad6f04" + "example": "cmllufwbz000a42jq38zw6ymi" } }, "required": ["bookmarkId"], @@ -2456,7 +2476,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmkwbc0m10009b0s0d05fapzk" + "example": "cmllufwbe000942jq2gbqaan5" }, "required": true, "description": "The Id of the collection to be deleted." @@ -2762,7 +2782,7 @@ "name": "collectionId", "schema": { "type": "string", - "example": "cmkwbc0ng000eb0s04gn2b009" + "example": "cmllufwcx000e42jqbbko1239" } }, { @@ -2807,7 +2827,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -2818,7 +2838,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -2850,11 +2870,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -3410,7 +3430,7 @@ "schema": { "type": "string", "description": "The Id of the collection to be deleted.", - "example": "cmkwbc0mu000cb0s0cm6n09p7" + "example": "cmllufwc7000c42jqgppy4l7i" }, "required": true, "description": "The Id of the collection to be deleted." @@ -3421,7 +3441,7 @@ "schema": { "type": "string", "description": "The Id of the bookmark to be deleted.", - "example": "cmkwbc0mu000db0s005p84503" + "example": "cmllufwc7000d42jqcssd1xyn" }, "required": true, "description": "The Id of the bookmark to be deleted." @@ -3777,7 +3797,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -3788,7 +3808,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -3811,11 +3831,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -4079,6 +4099,10 @@ "description": "The Ayah number to be added.", "example": 3 }, + "isReading": { + "type": "boolean", + "description": "Whether this bookmark is the reading bookmark. Only one reading bookmark per user." + }, "mushaf": { "type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 11, 19], @@ -4103,6 +4127,10 @@ "description": "The bookmark type.", "example": "surah" }, + "isReading": { + "type": "boolean", + "description": "Whether this bookmark is the reading bookmark. Only one reading bookmark per user." + }, "mushaf": { "type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 11, 19], @@ -4408,6 +4436,26 @@ "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", @@ -4454,7 +4502,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -4466,7 +4514,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -4490,11 +4538,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -4727,7 +4775,7 @@ "schema": { "type": "string", "description": "The id of the bookmark to be deleted.", - "example": "cmkwbc0j40006b0s0gh8bh75y" + "example": "cmllufw83000642jqazgfho39" }, "required": true, "description": "The id of the bookmark to be deleted." @@ -5091,11 +5139,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -5322,15 +5370,36 @@ "tags": ["Bookmarks"], "summary": "Get bookmark", "parameters": [ + { + "in": "query", + "name": "verseNumber", + "schema": { + "type": "integer", + "description": "The Ayah number of the bookmark" + }, + "required": false, + "description": "The Ayah number of the bookmark" + }, + { + "in": "query", + "name": "isReading", + "schema": { + "type": "boolean", + "description": "Whether to fetch the reading bookmark" + }, + "required": false, + "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 }, - "required": true, + "required": false, "description": "Surah, Juz or page number." }, { @@ -5339,22 +5408,13 @@ "schema": { "type": "string", "enum": ["page", "juz", "surah", "ayah"], + "oneOf": [{}, { "x-required": true }], "description": "The bookmark type.", "default": "ayah" }, "required": false, "description": "The bookmark type." }, - { - "in": "query", - "name": "verseNumber", - "schema": { - "type": "integer", - "description": "The Ayah number of the bookmark" - }, - "required": false, - "description": "The Ayah number of the bookmark" - }, { "in": "query", "name": "mushaf", @@ -5664,7 +5724,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "required": false, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" @@ -5676,7 +5736,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "required": false, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" @@ -6001,8 +6061,11 @@ "reflectionFontScale", "qnaFontScale", "lessonFontScale", + "surahInfoFontScale", + "hadithFontScale", "quranFont", - "mushafLines" + "mushafLines", + "showTajweedRules" ] } }, @@ -7328,7 +7391,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -7339,7 +7402,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -7362,11 +7425,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -7650,7 +7713,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmkwbc0ec0004b0s040lfctn8" + "example": "cmllufw2m000442jqb9o141br" }, "date": { "type": "string", @@ -7998,7 +8061,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmkwbc0oi000fb0s04c737onv" + "example": "cmllufwdv000f42jqe7ukd4my" }, "required": true, "description": "The id of the goal." @@ -8318,7 +8381,7 @@ "schema": { "type": "string", "description": "The id of the goal.", - "example": "cmkwbc0oi000fb0s04c737onv" + "example": "cmllufwdv000f42jqe7ukd4my" }, "required": true, "description": "The id of the goal." @@ -8677,7 +8740,7 @@ "id": { "type": "string", "description": "The id of the goal.", - "example": "cmkwbc0oi000fb0s04c737onv" + "example": "cmllufwdv000f42jqe7ukd4my" } }, "required": ["id"], @@ -9305,7 +9368,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -9316,7 +9379,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -9338,7 +9401,7 @@ "id": { "type": "string", "description": "The id of the streak.", - "example": "cmkwbc0zd000hb0s04j4j2nuj" + "example": "cmllufwnz000h42jq9fhh3626" }, "startDate": { "type": "string", @@ -9379,11 +9442,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -10245,7 +10308,7 @@ "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": "cmkwbc0dr0000b0s0fboz3anv" + "example": "cmllufw25000042jqhmcfez63" }, "description": "The cursor after which you want to get the next page of items. Should be used together with `first`" }, @@ -10256,7 +10319,7 @@ "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": "cmkwbc0ds0001b0s01bxvcw79" + "example": "cmllufw25000142jq27mq9zle" }, "description": "The cursor before which the previous page of items will be fetched. Should be used together with `last`" } @@ -10278,7 +10341,7 @@ "id": { "type": "string", "description": "The id of the activity day.", - "example": "cmkwbc0ec0004b0s040lfctn8" + "example": "cmllufw2m000442jqb9o141br" }, "date": { "type": "string", @@ -10402,11 +10465,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -11130,11 +11193,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -11884,11 +11947,11 @@ "properties": { "startCursor": { "type": "string", - "example": "cmkwbc0ds0002b0s0aeub15nr" + "example": "cmllufw25000242jq7syu6r8q" }, "endCursor": { "type": "string", - "example": "cmkwbc0ds0003b0s0a2whdvgb" + "example": "cmllufw26000342jq37j17vvo" }, "hasNextPage": { "type": "boolean", "example": true }, "hasPreviousPage": { @@ -16348,6 +16411,16 @@ "default": 5, "type": "number" } + }, + { + "name": "sortBy", + "required": false, + "in": "query", + "description": "Sort order (default: NAME_ASC)", + "schema": { + "enum": ["NAME_ASC", "NAME_DESC", "LATEST_ACTIVITY"], + "type": "string" + } } ], "responses": { @@ -16398,6 +16471,16 @@ "default": 5, "type": "number" } + }, + { + "name": "sortBy", + "required": false, + "in": "query", + "description": "Sort order (default: NAME_ASC)", + "schema": { + "enum": ["NAME_ASC", "NAME_DESC", "LATEST_ACTIVITY"], + "type": "string" + } } ], "responses": {